Como configurar pontes no Matrix: WhatsApp, Telegram e Discord

Para integrar o Matrix com o WhatsApp, Telegram ou Discord, execute um serviço de ponte compatível ao lado do seu servidor doméstico, registre esse serviço como um serviço de aplicativo do Matrix e, em seguida, vincule ou autorize a conta externa. Cada rede precisa de sua própria configuração de ponte e credenciais. Um processo em execução por si só não comprova que uma sala está conectada: teste o envio de uma mensagem em ambas as direções após a configuração.

Este guia utiliza o mautrix-whatsapp e o mautrix-telegram , além do projeto matrix-appservice-discord do Matrix.org para o Discord. Uma ponte é um programa separado do lado do servidor, não um switch no Element. A especificação do Matrix chama esse tipo de integração de serviço de aplicação: ele recebe eventos relevantes do servidor doméstico e pode criar usuários ou salas dentro do namespace registrado para ele. Consulte a visão geral técnica do Matrix e a especificação da API de Serviço de Aplicação .

Você deve hospedar as pontes em seu próprio servidor ou usar uma instância pública?

A hospedagem própria permite que você controle onde a ponte é executada, como os logs e as credenciais são armazenados e quais usuários podem se conectar. Isso também significa que você precisa manter três serviços, atualizá-los, proteger seus bancos de dados e solucionar problemas de conectividade. Uma ponte pública pode ser mais rápida para testar, mas seu operador controla a disponibilidade, a política de acesso e o gerenciamento de dados. Verifique a documentação e a sala de suporte da ponte antes de escolher uma instância; a disponibilidade e os recursos podem mudar.

Essas conexões não são equivalentes ao suporte nativo dos serviços de mensagens. Os recursos integrados podem variar de rede para rede, e chamadas de voz/vídeo, reações, edições, tópicos, confirmações de leitura, histórico ou administração de grupos podem estar incompletos. Teste os recursos dos quais sua comunidade realmente depende antes de migrar conversas importantes.

O que você precisa antes de instalar qualquer coisa?

• Um servidor doméstico Matrix que suporta serviços de aplicativos e acesso de administrador para registrá-los. Os exemplos abaixo usam o Synapse; outros servidores domésticos têm seus próprios processos de registro.
• Um caminho de rede acessível entre o servidor doméstico e cada ponte. No Docker, " localhostdentro de um contêiner" significa o próprio contêiner; use uma rede Docker compartilhada e o nome de rede do serviço de ponte quando o servidor doméstico precisar acessar outro contêiner.
• Cada ponte possui um arquivo de configuração, um arquivo de registro, um local para dados persistentes e um repositório de segredos separados. Siga as instruções atuais do projeto para obter informações sobre bancos de dados, versões de tempo de execução e imagens de contêiner compatíveis; os requisitos variam e estão sujeitos a alterações.
• Para o WhatsApp, é necessário um celular com a conta que você deseja vincular. Para o Telegram, é preciso uma conta já conectada por meio de um aplicativo oficial do Telegram. Para o Discord, é necessário um aplicativo/bot do Discord e a permissão do proprietário ou administrador do servidor.

Como registrar uma ponte no Synapse?

1. Implante uma ponte por vez. Comece com a versão atual e sua configuração de exemplo. Defina o endereço do servidor principal, o nome do servidor público, o endereço do ouvinte da ponte, o banco de dados e os caminhos de armazenamento de acordo com o guia do projeto. Evite compartilhar um banco de dados entre serviços de ponte não relacionados.
2. Gere o arquivo de registro. O processo de configuração da ponte cria um arquivo YAML de registro contendo a identidade do serviço de aplicação e os tokens de autenticação. Trate esses tokens como senhas: restrinja as permissões de arquivo, não os inclua no Git e não os compartilhe em salas públicas, capturas de tela ou posts de suporte.
3. Torne o arquivo visível para o Synapse. Copie ou monte o arquivo de registro em um local onde o processo do Synapse possa lê-lo. Adicione o caminho do arquivo abaixo app_service_config_filesno arquivo de configuração do Synapse homeserver.yaml. Adicione uma entrada de lista separada para cada bridge; não sobrescreva a entrada de outro serviço. O guia de registro de serviços de aplicativos da Mautrix descreve esse fluxo e observa que o Synapse deve ser reiniciado após a alteração da lista de registro.
4. Reinicie e verifique os logs. Reinicie o Synapse após uma alteração no registro e, em seguida, inicie a ponte. Se o Synapse não iniciar, verifique primeiro a indentação do YAML, o caminho do arquivo no contêiner e as permissões de leitura. Se a ponte iniciar, mas não conseguir se conectar, verifique o URL do servidor doméstico, a rota de rede, o certificado TLS e o endereço do listener.

Para implantações do Docker, o endereço do serviço de aplicação configurado na ponte deve ser acessível a partir do contêiner do servidor principal. As notas de configuração inicial do mautrix explicam por que um nome de contêiner em uma rede compartilhada pode funcionar onde localhostnão funciona. O projeto do Discord também documenta seu próprio fluxo de trabalho de registro e um exemplo de configuração no README do projeto original .

Como conectar uma conta do WhatsApp?

Após o mautrix-whatsapp estar registrado e em execução, abra um chat privado do Matrix com o bot de ponte e envie o código login qr. Abra o WhatsApp no ​​telefone que possui a conta, acesse Dispositivos vinculados e escaneie o código apresentado pelo bot de ponte. A documentação do bot de ponte também descreve uma opção de código de pareamento por número de telefone; use o método atualmente compatível com a sua versão instalada. Não copie um código de login ou imagem QR para uma sala pública.

Mantenha o telefone e a conta disponíveis durante o emparelhamento e confirme se o dispositivo de conexão reportou um login bem-sucedido antes de abrir as salas do portal. Isso vincula uma conta por meio de uma sessão no estilo de dispositivo complementar; não transforma o dispositivo de conexão em uma integração oficial da API do WhatsApp Business. O WhatsApp pode alterar o comportamento de vinculação de dispositivos, portanto, siga as instruções de autenticação atuais do mautrix-whatsapp . Um dispositivo de conexão pode sincronizar apenas o histórico que o serviço externo disponibiliza para o dispositivo vinculado e que o dispositivo de conexão implementa.

Como conectar o Telegram?

Inicie um bate-papo privado com o bot mautrix-telegram. A ponte suporta login por QR Code e um código de seis dígitos enviado para um cliente Telegram já conectado; ela não cria uma nova conta Telegram. Para login por QR Code, abra o Telegram no seu celular, vá em Configurações > Dispositivos > Vincular dispositivo de mesa , envie login qro código para o bot da ponte e escaneie-o. Siga as instruções do bot se a verificação em duas etapas estiver ativada na sua conta Telegram.

Use uma conta já existente e siga as regras de login do Telegram. Os responsáveis ​​pela ponte alertam que o Telegram pode tratar novas contas que utilizam clientes de terceiros como suspeitas; esse é um risco da plataforma, não algo que um administrador do Matrix possa garantir que seja totalmente eliminado. Leia o guia de autenticação do mautrix-telegram antes de fazer login e mantenha qualquer código de uso único ou senha dentro do chat privado do bot.

Como configurar o Discord?

O projeto matrix-appservice-discord utiliza um aplicativo e um bot do Discord. Crie o aplicativo no Portal do Desenvolvedor do Discord , crie/configure o usuário do bot e defina as credenciais do bot na configuração da ponte usando o exemplo atual do projeto. Não exponha o token do bot. Execute o comando ou fluxo authorization-link documentado da ponte e, em seguida, peça ao administrador de um servidor Discord que autorize o bot para o servidor desejado, concedendo apenas as permissões necessárias à ponte.

Para um canal específico, obtenha os IDs do servidor e do canal usando as ferramentas de desenvolvedor do Discord, convide o bot de ponte do lado do Matrix para a sala do Matrix e use o comando de sala documentado da ponte. O README original fornece um exemplo no formato !discord bridge ServerID ChannelID; uma etapa de aprovação de administrador pode ser necessária para concluir o link. Não use os IDs da ilustração: substitua-os pelos identificadores reais e confirme o comando e as permissões consultando o README da sua versão instalada.

O Discord depende especialmente das permissões do bot e das políticas do servidor. Se o bot conseguir entrar, mas as mensagens não forem transmitidas, verifique se o canal está visível para ele, se as permissões de mensagem necessárias foram concedidas e se a ponte concluiu todas as confirmações de administrador. O projeto se autodenomina beta em seu arquivo README, portanto, confirme o status atual do projeto e o comportamento suportado em vez de presumir que todos os recursos do Discord estejam presentes.

Como você pode verificar se a ponte funciona?

Use inicialmente uma pequena sala de testes privada e um canal de baixo risco. Envie uma mensagem de texto simples exclusiva do Matrix e confirme se ela aparece no serviço remoto; em seguida, responda do lado remoto e confirme se a resposta aparece no Matrix. Verifique a atribuição, o agrupamento das respostas, os anexos, as edições e as reações separadamente, caso sejam relevantes para o seu caso de uso. Um status verde do processo indica apenas que o programa está em execução: não garante que o login foi bem-sucedido, que o bot tem acesso ao canal ou que o mapeamento entre sala e canal está correto.

Quando um teste falhar, compare o horário exato da mensagem com os logs da ponte e do servidor doméstico. Oculte tokens de acesso, números de telefone, IDs do Discord (se houver) e nomes de contato antes de compartilhar os logs. Para implantações em contêineres, verifique também se o arquivo de registro está montado no Synapse, se o endpoint da ponte resolve na rede compartilhada e se nenhum firewall está bloqueando o listener configurado.

O que você deve saber sobre criptografia e privacidade?

Os serviços de aplicação recebem eventos nos namespaces e salas para os quais estão configurados. Não assuma que uma sala Matrix criptografada seja automaticamente legível por todas as bridges. Algumas bridges do mautrix suportam criptografia de ponta a ponta, que deve ser configurada manualmente e possui seus próprios requisitos de gerenciamento de chaves; consulte o guia de criptografia de ponta a ponta do mautrix e verifique a compatibilidade com a bridge específica. Os recursos de criptografia das bridges do Discord podem variar. Se uma bridge não for compatível com o modo de criptografia da sala, use uma sala de teste não criptografada adequada ou escolha uma bridge com suporte documentado, em vez de enfraquecer uma sala de produção por tentativa e erro.

Por fim, lembre-se de que o conteúdo das mensagens e as credenciais da conta passam por um software operado por você ou por um operador de ponte pública. Limite quem pode convidar bots para a ponte, proteja bancos de dados e backups, troque o token caso ele vaze e revise as diretrizes de privacidade e segurança da ponte. Verifique novamente a documentação original antes de atualizações: chaves de configuração, fluxos de login, dependências e políticas da plataforma podem mudar independentemente.

Lista de verificação para tomada de decisão rápida

• Escolha uma instância de ponte cujo operador e política de acesso você considere confiáveis.
• Registre cada ponte separadamente e proteja cada token gerado.
• Verifique se o servidor doméstico consegue alcançar o endereço da ponte após a implantação.
• Vincule as contas do WhatsApp/Telegram de forma privada e autorize o bot do Discord com um administrador do servidor.
• Teste as mensagens em ambas as direções e, em seguida, teste apenas os recursos adicionais de que você precisa.
• Antes de utilizar a ponte para comunicações sensíveis ou essenciais, confirme o suporte à criptografia, o histórico de comportamento e o estado de manutenção.