How to Configure Bridges in Matrix: WhatsApp, Telegram, and Discord
To bridge Matrix with WhatsApp, Telegram, or Discord, run a compatible bridge service beside your homeserver, register that service as a Matrix application service, and then link or authorize the external account. Each network needs its own bridge configuration and credentials. A running process alone does not prove that a room is bridged: test a message in both directions after setup.
One Matrix homeserver can connect to three separately configured bridge services.
Should you self-host the bridges or use a public instance?
Self-hosting gives you control over where the bridge runs, how logs and credentials are stored, and which users may connect. It also means you maintain three services, update them, protect their databases, and troubleshoot connectivity. A public bridge can be faster to try, but its operator controls availability, access policy, and data handling. Check the bridge's current documentation and support room before choosing an instance; availability and features can change.
These connections are not equivalent to native support from the messaging services. Bridged features may differ from network to network, and voice/video calls, reactions, edits, threads, read receipts, history, or group administration may be incomplete. Test the features your community actually depends on before moving important conversations.
What do you need before installing anything?
A Matrix homeserver that supports application services and administrator access to register them. The examples below use Synapse; other homeservers have their own registration process.
A reachable network path between the homeserver and each bridge. In Docker, localhost inside one container means that container itself; use a shared Docker network and the bridge service's network name when the homeserver must reach another container.
A separate configuration, registration file, persistent data location, and secret store for each bridge. Follow the current project instructions for supported databases, runtime versions, and container images; requirements differ and change.
Para WhatsApp, necesitas un teléfono con la cuenta que deseas vincular. Para Telegram, necesitas una cuenta con la sesión iniciada a través de un cliente oficial de Telegram. Para Discord, necesitas una aplicación o bot de Discord y el permiso del propietario o administrador del servidor.
Synapse lee cada archivo de registro de puente desde la ruta configurada en app_service_config_files; las rutas que se muestran son ejemplos.
¿Cómo se registra un puente con Synapse?
Implemente un puente a la vez. Comience con una versión reciente y su configuración de ejemplo. Configure la dirección del servidor principal, el nombre del servidor público, la dirección del oyente del puente, la base de datos y las rutas de almacenamiento según la guía del proyecto. Evite compartir una base de datos entre servicios de puente no relacionados.
Genera el archivo de registro. El proceso de configuración del puente crea un archivo YAML de registro que contiene tokens de identidad y autenticación del servicio de la aplicación. Trata estos tokens como contraseñas: restringe los permisos de archivo, no los subas a Git y no los pegues en salas públicas, capturas de pantalla ni publicaciones de soporte.
Haz que Synapse pueda visualizar el archivo. Copia o monta el archivo de registro en una ubicación donde Synapse pueda leerlo. Agrega su ruta app_service_config_filesen la configuración de Synapse homeserver.yaml. Agrega una entrada de lista independiente para cada puente; no sobrescribas la entrada de otro servicio. La guía de registro de mautrix appservice describe este proceso e indica que Synapse debe reiniciarse después de que cambie la lista de registro.
Reinicia y revisa los registros. Reinicia Synapse después de un cambio de registro y luego inicia el puente. Si Synapse no se inicia, verifica primero la indentación de YAML, la ruta del archivo dentro del contenedor y los permisos de lectura. Si el puente se inicia pero no puede conectarse, verifica la URL del servidor principal, la ruta de red, el certificado TLS y la dirección del oyente.
Para las implementaciones de Docker, la dirección del servicio de aplicación configurada del puente debe ser accesible desde el contenedor del servidor principal. Las notas de configuración inicial de mautrix explican por qué un nombre de contenedor en una red compartida puede funcionar donde localhostno lo hace. El proyecto de Discord también documenta su propio flujo de trabajo de registro y una configuración de ejemplo en el archivo README original .
¿Cómo se conecta una cuenta de WhatsApp?
Una vez registrado y en funcionamiento mautrix-whatsapp, abre un chat privado de Matrix con su bot puente y envía un mensaje login qr. Abre WhatsApp en el teléfono propietario de la cuenta, ve a Dispositivos vinculados y escanea el código que te muestra el puente. La documentación del puente también describe una opción de código de emparejamiento de número de teléfono; usa el método compatible con tu versión instalada. No copies un código de inicio de sesión ni una imagen QR en una sala pública.
El proceso de autenticación del puente de WhatsApp te pide que vincules el puente como un dispositivo desde la cuenta de WhatsApp en tu teléfono.
Mantén el teléfono y la cuenta disponibles durante el emparejamiento y confirma que el puente reporte un inicio de sesión exitoso antes de abrir las salas del portal. Esto vincula una cuenta a través de una sesión de tipo dispositivo complementario; no convierte el puente en una integración oficial de la API de WhatsApp Business. WhatsApp podría cambiar el comportamiento de vinculación de dispositivos, así que sigue las instrucciones de autenticación de mautrix-whatsapp vigentes . Un puente solo puede sincronizar el historial que el servicio externo pone a disposición de un dispositivo vinculado y que el puente implementa.
¿Cómo se conecta Telegram?
Inicia un chat privado con el bot mautrix-telegram. El puente admite el inicio de sesión mediante código QR y un código de seis dígitos enviado a un cliente de Telegram con sesión iniciada; no crea una nueva cuenta de Telegram. Para iniciar sesión con el código QR, abre Telegram en tu teléfono, ve a Ajustes > Dispositivos > Vincular dispositivo de escritorio y envíalo login qral bot puente para escanear el código. Sigue las instrucciones del bot si tu cuenta de Telegram tiene la verificación en dos pasos activada.
La pantalla Link Desktop Device de Telegram se utiliza para autorizar la sesión de puente; las etiquetas del menú pueden variar según la versión de la aplicación.
Utiliza una cuenta ya existente y sigue las reglas de inicio de sesión de Telegram. Los responsables del puente advierten que Telegram podría considerar sospechosas las cuentas nuevas que utilicen clientes de terceros; este es un riesgo de la plataforma, algo que un administrador de Matrix no puede garantizar que se elimine. Revisa la guía de autenticación de mautrix-telegram antes de iniciar sesión y guarda cualquier código de un solo uso o contraseña en el chat privado del bot.
¿Cómo se configura Discord?
El proyecto matrix-appservice-discord utiliza una aplicación y un bot de Discord. Crea la aplicación en el Portal para desarrolladores de Discord , crea y configura el usuario del bot y establece las credenciales del bot en la configuración del puente utilizando el ejemplo actual del proyecto. No expongas el token del bot. Ejecuta el comando o flujo de autorización documentado del puente y, a continuación, solicita al propietario de un servidor de Discord que autorice al bot para el servidor correspondiente con solo los permisos que requiere el puente.
La configuración de Discord comienza con una aplicación y un bot; los campos exactos y las opciones de autorización siguen el portal actual de Discord y la configuración de ejemplo del puente.
Para un canal específico, obtenga su ID de servidor y canal usando las herramientas para desarrolladores compatibles de Discord, invite al bot puente de Matrix a la sala de Matrix y use el comando de sala documentado del puente. El archivo README original proporciona un ejemplo en el formato !discord bridge ServerID ChannelID; es posible que se requiera la aprobación de un administrador para completar el enlace. No use los ID de la ilustración: reemplácelos con los identificadores reales y confirme el comando y los permisos con el archivo README de su versión instalada.
El comando de sala de Discord asocia una sala de Matrix con un servidor y un canal de Discord; sustituya las identificaciones reales y siga las instrucciones de aprobación.
Discord depende especialmente de los permisos del bot y de la política del servidor. Si el bot puede unirse pero no se envían mensajes, compruebe que el canal sea visible para él, que se hayan otorgado los permisos de mensaje necesarios y que el puente haya completado cualquier confirmación del administrador. El proyecto se identifica como beta en su archivo README, por lo que conviene confirmar el estado actual del proyecto y el comportamiento compatible en lugar de asumir que todas las funciones de Discord están replicadas.
¿Cómo se puede verificar que el puente funciona?
Primero, utilice una pequeña sala de pruebas privada y un canal de bajo riesgo. Envíe un mensaje único en texto plano desde Matrix y confirme que aparece en el servicio remoto; luego, responda desde el lado remoto y confirme que la respuesta aparece en Matrix. Verifique por separado la atribución, la organización de la respuesta, los archivos adjuntos, las ediciones y las reacciones si son relevantes para su caso de uso. Un estado de proceso verde solo indica que el programa se está ejecutando: no confirma que el inicio de sesión haya sido exitoso, que el bot tenga acceso al canal o que la asignación de sala a canal sea correcta.
Una comprobación integral útil consiste en enviar un mensaje de prueba en cada dirección y verificar que su contraparte aparezca en la sala vinculada.
Cuando una prueba falla, compare la hora exacta del mensaje con los registros del puente y del servidor principal. Oculte los tokens de acceso, los números de teléfono, los ID de Discord (si son confidenciales) y los nombres de contacto antes de compartir los registros. Para implementaciones en contenedores, verifique también que el archivo de registro esté montado dentro de Synapse, que el punto final del puente se resuelva en la red compartida y que ningún firewall bloquee el oyente configurado.
Utilice los registros del puente y del servidor principal para comprobar el estado y la conectividad del proceso; estas líneas de estado de ejemplo no son un resultado de diagnóstico capturado.
¿Qué debes saber sobre el cifrado y la privacidad?
Los servicios de la aplicación reciben eventos en los espacios de nombres y salas que están configurados para gestionar. No asuma que una sala Matrix cifrada es legible automáticamente por todos los puentes. Algunos puentes mautrix admiten el cifrado de extremo a extremo, que debe configurarse explícitamente y tiene sus propios requisitos de gestión de claves; consulte la guía de cifrado de extremo a extremo de mautrix y verifique la compatibilidad con el puente específico. Las capacidades de cifrado de los puentes de Discord pueden variar. Si un puente no puede gestionar el modo de cifrado de la sala, utilice una sala de prueba sin cifrar adecuada o elija un puente con soporte documentado en lugar de debilitar una sala de producción por suposiciones.
Finalmente, recuerde que el contenido de los mensajes y las credenciales de la cuenta se transmiten a través del software que usted o un operador de puente público gestiona. Limite quién puede invitar a los bots del puente, proteja las bases de datos y las copias de seguridad, rote el token si se filtra y revise las directrices de privacidad y seguridad vigentes del puente. Revise la documentación original antes de actualizar: las claves de configuración, los flujos de inicio de sesión, las dependencias y las políticas de la plataforma pueden cambiar de forma independiente.
Lista de verificación para decisiones rápidas
Elija una instancia de puente cuyo operador y política de acceso le inspiren confianza.
Registre cada puente por separado y proteja cada token generado.
Verifique que el servidor principal pueda acceder a la dirección del puente después de la implementación.
Vincula tus cuentas de WhatsApp/Telegram de forma privada y autoriza el bot de Discord con un administrador del servidor.
Prueba los mensajes en ambas direcciones y, a continuación, prueba solo las funciones adicionales que necesites.
Confirme la compatibilidad con el cifrado, el comportamiento histórico y el estado de mantenimiento antes de utilizar el puente para comunicaciones sensibles o esenciales.