Come configurare i bridge in Matrix: WhatsApp, Telegram e Discord

Per collegare Matrix con WhatsApp, Telegram o Discord, esegui un servizio bridge compatibile accanto al tuo homeserver, registra tale servizio come servizio applicativo di Matrix e quindi collega o autorizza l'account esterno. Ogni rete richiede una configurazione bridge e credenziali specifiche. La sola esecuzione di un processo non garantisce che una stanza sia collegata: dopo la configurazione, testa l'invio e la ricezione di un messaggio in entrambe le direzioni.

Questa guida utilizza mautrix-whatsapp e mautrix-telegram , oltre al progetto matrix-appservice-discord di Matrix.org per Discord. Un bridge è un programma separato lato server, non un interruttore in Element. La specifica Matrix definisce questo tipo di integrazione un servizio applicativo: riceve gli eventi rilevanti del server principale e può creare utenti o stanze all'interno del namespace registrato per esso. Consultare la panoramica tecnica di Matrix e la specifica API del servizio applicativo .

È meglio ospitare i bridge in locale o utilizzare un'istanza pubblica?

L'hosting autonomo ti offre il controllo su dove viene eseguito il bridge, su come vengono archiviati i log e le credenziali e su quali utenti possono connettersi. Significa anche che dovrai gestire tre servizi, aggiornarli, proteggere i relativi database e risolvere i problemi di connettività. Un bridge pubblico può essere più veloce da testare, ma il suo gestore controlla la disponibilità, le politiche di accesso e la gestione dei dati. Prima di scegliere un'istanza, consulta la documentazione e l'area di supporto del bridge; la disponibilità e le funzionalità possono variare.

Queste connessioni non sono equivalenti al supporto nativo dei servizi di messaggistica. Le funzionalità collegate possono variare da rete a rete e le chiamate vocali/video, le reazioni, le modifiche, le conversazioni, le conferme di lettura, la cronologia o l'amministrazione dei gruppi potrebbero essere incomplete. Prima di spostare conversazioni importanti, testa le funzionalità di cui la tua community ha effettivamente bisogno.

Di cosa hai bisogno prima di installare qualsiasi cosa?

• Un homeserver Matrix che supporta i servizi applicativi e l'accesso amministrativo per la loro registrazione. Gli esempi seguenti utilizzano Synapse; altri homeserver hanno un proprio processo di registrazione.
• Un percorso di rete raggiungibile tra l'homeserver e ciascun bridge. In Docker, " localhostall'interno di un container" si riferisce al container stesso; utilizzare una rete Docker condivisa e il nome di rete del servizio bridge quando l'homeserver deve raggiungere un altro container.
• Per ogni bridge è necessario un file di configurazione, un file di registrazione, una posizione per i dati persistenti e un archivio segreto separati. Attenersi alle istruzioni di progetto correnti per i database supportati, le versioni di runtime e le immagini dei container; i requisiti sono diversi e soggetti a modifiche.
• Per WhatsApp, è necessario un telefono con l'account che si intende collegare. Per Telegram, è necessario un account già connesso tramite un client Telegram ufficiale. Per Discord, è necessaria l'applicazione/bot Discord e l'autorizzazione del proprietario o dell'amministratore del server.

Come si registra un bridge con Synapse?

1. Distribuisci un bridge alla volta. Inizia con una versione corrente e la relativa configurazione di esempio. Imposta l'indirizzo del server principale, il nome del server pubblico, l'indirizzo del listener del bridge, il database e i percorsi di archiviazione in base alla guida del progetto. Evita di condividere lo stesso database tra servizi bridge non correlati.
2. Genera il file di registrazione. Il processo di configurazione del bridge crea un file YAML di registrazione contenente l'identità del servizio applicativo e i token di autenticazione. Tratta questi token come password: limita i permessi di accesso ai file, non caricarli su Git e non incollarli in stanze pubbliche, screenshot o post di supporto.
3. Rendi il file visibile a Synapse. Copia o monta il file di registrazione in una posizione accessibile al processo Synapse. Aggiungi il suo percorso app_service_config_filesnella directory di Synapse homeserver.yaml. Aggiungi una voce di elenco separata per ogni bridge; non sovrascrivere la voce di un altro servizio. La guida alla registrazione di mautrix appservice descrive questo flusso e precisa che Synapse deve essere riavviato dopo ogni modifica all'elenco di registrazione.
4. Riavvia e controlla i log. Riavvia Synapse dopo una modifica della registrazione, quindi avvia il bridge. Se Synapse non si avvia, controlla prima l'indentazione YAML, il percorso del file all'interno del container e i permessi di lettura. Se il bridge si avvia ma non riesce a connettersi, controlla l'URL del server principale, il percorso di rete, il certificato TLS e l'indirizzo del listener.

Per le implementazioni Docker, l'indirizzo del servizio applicativo configurato sul bridge deve essere raggiungibile dal container del server principale. Le note di configurazione iniziale di mautrix spiegano perché un nome di container su una rete condivisa potrebbe funzionare dove localhostnon funziona. Il progetto Discord documenta anche il proprio flusso di lavoro di registrazione e la configurazione di esempio nel file README originale .

Come si collega un account WhatsApp?

Dopo aver registrato e avviato mautrix-whatsapp, apri una chat privata Matrix con il suo bot bridge e invia il codice QR login qr. Apri WhatsApp sul telefono a cui appartiene l'account, vai su Dispositivi collegati e scansiona il codice visualizzato dal bridge. La documentazione del bridge descrive anche un'opzione per il codice di abbinamento del numero di telefono; utilizza il metodo attualmente supportato dalla versione installata. Non copiare un codice di accesso o un'immagine QR in una chat pubblica.

Durante l'associazione, assicurati che il telefono e l'account siano disponibili e verifica che il bridge segnali un accesso riuscito prima di aprire le stanze del portale. Questo collega un account tramite una sessione in stile dispositivo complementare; non trasforma il bridge in un'integrazione ufficiale dell'API di WhatsApp Business. WhatsApp potrebbe modificare il comportamento di collegamento dei dispositivi, quindi segui le istruzioni di autenticazione mautrix-whatsapp aggiornate . Un bridge può sincronizzare solo la cronologia che il servizio esterno rende disponibile a un dispositivo collegato e che il bridge implementa.

Come si collega Telegram?

Avvia una chat privata con il bot mautrix-telegram. Il bridge supporta l'accesso tramite codice QR e un codice di accesso a sei cifre inviato a un client Telegram già connesso; non registra un nuovo account Telegram. Per l'accesso tramite codice QR, apri Telegram sul tuo telefono, vai su Impostazioni > Dispositivi > Collega dispositivo desktop , quindi invia login qril codice al bot e scansionalo. Segui le istruzioni del bot se il tuo account Telegram ha la verifica in due passaggi abilitata.

Utilizza un account già esistente e segui le regole di accesso di Telegram. Gli amministratori del bridge avvertono che Telegram potrebbe considerare sospetti i nuovi account che utilizzano client di terze parti; si tratta di un rischio lato piattaforma, non qualcosa che un amministratore di Matrix può garantire di eliminare. Consulta la guida all'autenticazione di mautrix-telegram prima di accedere e conserva qualsiasi codice monouso o password nella chat privata del bot.

Come si configura Discord?

Il progetto matrix-appservice-discord utilizza un'applicazione e un bot Discord. Crea l'applicazione nel portale per sviluppatori di Discord , crea/configura l'utente bot e imposta le credenziali del bot nella configurazione del bridge utilizzando l'esempio corrente del progetto. Non esporre il token del bot. Esegui il comando o il flusso di autorizzazione documentato del bridge, quindi chiedi al proprietario del server Discord di autorizzare il bot per il server desiderato con le sole autorizzazioni richieste dal bridge.

Per un canale specifico, ottieni gli ID del server e del canale utilizzando gli strumenti per sviluppatori supportati da Discord, invita il bot bridge lato Matrix alla stanza Matrix e usa il comando di stanza documentato del bridge. Il file README originale fornisce un esempio nel formato !discord bridge ServerID ChannelID; potrebbe essere necessario un passaggio di approvazione da parte di un amministratore per completare il collegamento. Non utilizzare gli ID dell'esempio: sostituiscili con gli identificativi effettivi e verifica il comando e le autorizzazioni nel file README della versione installata.

Discord dipende in particolare dai permessi dei bot e dalle policy del server. Se il bot riesce ad accedere ma i messaggi non vengono visualizzati, verifica che il canale sia visibile al bot, che siano stati concessi i permessi di invio messaggi necessari e che il bridge abbia completato tutte le verifiche amministrative. Il progetto si definisce in versione beta nel suo README, quindi verifica lo stato attuale del progetto e il comportamento supportato, anziché presumere che ogni funzionalità di Discord sia replicata.

Come si può verificare che il ponte funzioni?

Utilizzate innanzitutto una piccola stanza di prova privata e un canale a basso rischio. Inviate un messaggio di testo semplice univoco da Matrix e verificate che venga visualizzato sul servizio remoto; quindi rispondete dal lato remoto e verificate che la risposta venga visualizzata in Matrix. Controllate separatamente l'attribuzione, la struttura delle conversazioni, gli allegati, le modifiche e le reazioni, se rilevanti per il vostro caso d'uso. Uno stato di processo verde indica solo che il programma è in esecuzione: non stabilisce che l'accesso sia andato a buon fine, che il bot abbia accesso al canale o che la mappatura stanza-canale sia corretta.

Quando un test fallisce, confronta l'ora esatta del messaggio con i log del bridge e dell'homeserver. Oscura i token di accesso, i numeri di telefono, gli ID Discord (se sensibili) e i nomi dei contatti prima di condividere i log. Per le implementazioni in container, verifica anche che il file di registrazione sia montato all'interno di Synapse, che l'endpoint del bridge sia risolvibile sulla rete condivisa e che nessun firewall blocchi il listener configurato.

Cosa dovresti sapere sulla crittografia e la privacy?

I servizi applicativi ricevono eventi negli spazi dei nomi e nelle stanze che sono configurati per gestire. Non dare per scontato che una stanza Matrix crittografata sia automaticamente leggibile da ogni bridge. Alcuni bridge Mautrix supportano la crittografia end-to-bridge, che deve essere configurata esplicitamente e ha requisiti specifici per la gestione delle chiavi; consulta la guida alla crittografia end-to-bridge di Mautrix e verifica il supporto per il bridge specifico. Le funzionalità di crittografia dei bridge Discord possono variare. Se un bridge non è in grado di gestire la modalità di crittografia della stanza, utilizza una stanza di test non crittografata appropriata o scegli un bridge con supporto documentato anziché compromettere una stanza di produzione con tentativi a caso.

Infine, ricorda che il contenuto dei messaggi e le credenziali dell'account transitano attraverso software gestiti da te o da un operatore di bridge pubblico. Limita chi può invitare bot sul bridge, proteggi database e backup, ruota un token in caso di fuga di dati e rivedi le linee guida sulla privacy e la sicurezza del bridge. Ricontrolla la documentazione a monte prima degli aggiornamenti: chiavi di configurazione, flussi di accesso, dipendenze e politiche della piattaforma possono cambiare indipendentemente.

Lista di controllo per decisioni rapide

• Scegli un'istanza bridge di cui ti fidi, sia per quanto riguarda l'operatore che per la politica di accesso.
• Registra ogni bridge separatamente e proteggi ogni token generato.
• Verificare che il server domestico possa raggiungere l'indirizzo del bridge dopo la distribuzione.
• Collega privatamente gli account WhatsApp/Telegram e autorizza il bot Discord con un amministratore del server.
• Testa i messaggi in entrambe le direzioni, poi testa solo le funzionalità aggiuntive di cui hai bisogno.
• Prima di utilizzare il bridge per comunicazioni sensibili o essenziali, verificare il supporto alla crittografia, il comportamento storico e lo stato di manutenzione.