nolith.dev / iliadvoicemail-to-matrix
A Cloudflare worker that receives ILIAD voicemails and forward them to Matrix
fork atom
TypeScript 99.6%
Nix 0.4%
Other 0.1%
4 1 0

Clone this repository

https://tangled.org/nolith.dev/iliadvoicemail-to-matrix https://tangled.org/did:plc:nzep3slobztdph3kxswzbing/iliadvoicemail-to-matrix
git@tangled.org:nolith.dev/iliadvoicemail-to-matrix git@tangled.org:did:plc:nzep3slobztdph3kxswzbing/iliadvoicemail-to-matrix

For self-hosted knots, clone URLs may differ based on your setup.

Download tar.gz
README.md

iliadvoicemail-to-matrix#

Worker di Cloudflare che riceve email tramite Email Routing e le inoltra in una stanza Matrix.

Il caso principale supportato e' la segreteria telefonica di ILIAD:

  • se l'email proviene da vms@iliad.it e contiene un allegato audio, il worker carica l'audio su Matrix
  • invia un evento m.audio nella stanza configurata
  • se riesce a estrarre i metadati dal testo del messaggio, invia anche una nota nel thread con mittente, data e durata

Per le altre email, il worker invia un messaggio di testo con oggetto, mittente e corpo, poi carica eventuali allegati audio come messaggi Matrix separati.

Configurazione richiesta#

Il worker usa queste variabili di configurazione:

  • MATRIX_HOMESERVER: URL dell'homeserver Matrix
  • MATRIX_ROOM_ID: room ID della stanza di destinazione
  • MATRIX_ACCESS_TOKEN: access token Matrix usato per inviare messaggi e caricare media

Nel repository, wrangler.jsonc contiene solo valori di esempio pubblici per MATRIX_HOMESERVER e MATRIX_ROOM_ID. Non sono valori reali di deploy.

Modello di configurazione#

Questo progetto usa una separazione esplicita tra configurazione di esempio, configurazione locale e configurazione di deploy:

  • wrangler.jsonc: contiene la configurazione strutturale del worker e placeholder pubblici
  • .dev.vars: contiene i valori reali per lo sviluppo locale ed e' ignorato da git
  • dashboard di Cloudflare: contiene le variabili reali di deploy per MATRIX_HOMESERVER e MATRIX_ROOM_ID
  • secret di Cloudflare: contiene MATRIX_ACCESS_TOKEN per il deploy

In wrangler.jsonc e' attivo keep_vars: true. Questo serve a evitare che wrangler deploy cancelli le variabili gestite nella dashboard di Cloudflare.

Sviluppo locale#

  1. Crea un file .dev.vars nella root del progetto.
  2. Copia i nomi delle variabili da .dev.vars.example.
  3. Inserisci i tuoi valori reali.

Esempio:

MATRIX_HOMESERVER="https://matrix.example.com"
MATRIX_ROOM_ID="!your-room-id:example.com"
MATRIX_ACCESS_TOKEN="replace-me"

Per lo sviluppo locale, Wrangler carica .dev.vars e rende queste variabili disponibili nel parametro env del worker.

Configurazione di deploy#

Per il deploy usa questo percorso canonico:

  • imposta MATRIX_HOMESERVER e MATRIX_ROOM_ID come variabili nella configurazione runtime del Worker su Cloudflare
  • imposta MATRIX_ACCESS_TOKEN come secret del Worker su Cloudflare

I valori presenti in wrangler.jsonc sono solo placeholder e non devono essere usati come configurazione reale.

Comandi utili#

  • nix develop - apre una shell con node e wrangler
  • npm run dev - avvia wrangler dev
  • npm run deploy - esegue wrangler deploy
  • npm run generate-types - rigenera worker-configuration.d.ts
  • npm test - esegue la suite Vitest

Comportamento del worker#

Quando arriva un'email:

  1. il worker la parse tramite postal-mime
  2. legge il corpo testuale
  3. costruisce la configurazione Matrix da env
  4. distingue tra email ILIAD e email generiche
  5. invia testo, audio e note thread su Matrix tramite Client-Server API

Se l'invio a Matrix fallisce oppure l'email non contiene un corpo testuale valido, il worker rifiuta il messaggio.

Note importanti#

  • la guida documenta solo il flusso dell'ambiente di default
  • .dev.vars serve solo in locale e non configura il deploy
  • keep_vars: true aiuta a preservare le variabili gestite su Cloudflare, ma non sostituisce la configurazione iniziale delle variabili o dei secret