Conectar o Telegram: guia passo a passo
Envia alertas em caso de falha (um por teste com NEXUS_TELEGRAM_NOTIFY=true) e os relatórios e arquivos que você escolher compartilhar, por meio de um bot próprio. Não há um bot compartilhado. Este guia leva você do zero a uma conexão verificada e lista os erros que podem ocorrer, com suas causas e soluções.
Última atualização:
Mantenha suas credenciais em sigilo. Nunca cole um token, uma chave, uma senha ou uma URL de webhook em uma conversa. Insira esses dados apenas em Studio → Configurações → Integrações, onde são salvos no arquivo .env do seu espaço de trabalho e exibidos como pontos. O mesmo vale para um assistente de IA: ele pode orientar você neste guia, mas nunca precisa do seu token.
O que você precisa
- Uma conta do Telegram.
- Um bot próprio, criado uma única vez com @BotFather, e seu token.
- Um celular ou aplicativo do Telegram para ler o código QR de pareamento.
- Antes de ativar: o Telegram pode receber arquivos como relatórios e PDFs, que são enviados aos servidores do Telegram. Em um ambiente regulamentado, consulte primeiro sua equipe de conformidade.
Obtenha as credenciais
- No Telegram, abra https://t.me/BotFather e envie /newbot. Dê ao bot um nome e um nome de usuário.
- O BotFather responde com o token do bot (por exemplo 123456:ABC…). Copie-o.
- Mantenha-o na área de transferência. Não o cole em nenhum lugar além do Studio (próxima etapa).
Conecte no Studio
- No Studio, abra Configurações → Integrações → Conectar o Telegram.
- Cole o token do bot e salve. O código QR de pareamento aparece.
- Leia o código QR com seu celular e toque em Iniciar no Telegram. Em segundos, o Studio mostra "os alertas vão para a conversa …" e o bot diz "Conectado ao Nexus StudioQA."
- Ative
TELEGRAM_ENABLED. Para receber um alerta por teste com falha, ative tambémNEXUS_TELEGRAM_NOTIFY.
Verifique se funciona
- Após a leitura do código, o bot envia "Conectado ao Nexus StudioQA. Os testes com falha serão informados aqui." para sua conversa.
- O Studio mostra "os alertas vão para a conversa" com a identificação da conversa mascarada.
Erros comuns
| O que você vê | Causa | Solução |
|---|---|---|
| "O Telegram está desativado" | TELEGRAM_ENABLED está definido como false, e o pareamento exige que esteja ativado. | Ative TELEGRAM_ENABLED e pressione Conectar o Telegram novamente. |
| "Nenhum token de bot" | TELEGRAM_TOKEN está vazio. | Cole o token do BotFather em Configurações → Integrações e salve. |
| "Telegram: Não autorizado" (ou "Não encontrado") | O token do bot está incorreto, foi revogado no BotFather ou foi cortado ao ser copiado. | Envie /token ao BotFather para obter o token novamente (ou crie um novo bot) e salve-o. |
| "O código QR expirou antes de ser lido" | O código QR é válido por apenas alguns minutos. | Pressione Conectar Telegram para gerar um novo código e leia-o imediatamente. |
| O código QR foi lido, mas o Studio continua aguardando | A leitura abriu a conversa, mas você não tocou em Iniciar, ou a janela do Studio foi fechada. | Toque em Iniciar na conversa com o bot. Se o Studio continuar aguardando, gere um novo código QR. |
| "não foi possível acessar o Telegram (ENOTFOUND)" ou "não respondeu em 20 s" | Este PC não consegue acessar api.telegram.org: uma VPN, firewall ou proxy está bloqueando o acesso, ou não há conexão de rede. | Verifique a rede no mesmo PC e tente novamente. |
| Nenhum alerta chega após uma falha | TELEGRAM_ENABLED está definido como false, nenhuma conversa está pareada ou os alertas por teste estão desativados (NEXUS_TELEGRAM_NOTIFY). | Pareie uma conversa e ative as duas opções. |
Chaves de configuração
| Chave | O que faz | Valor válido | Como verificar |
|---|---|---|---|
TELEGRAM_ENABLED | Enviar alertas para o Telegram | true ou false | Esta opção precisa estar ativada para usar o código QR de pareamento. |
TELEGRAM_TOKEN | Código de acesso do bot do Telegram (secreto, salvo apenas neste computador) | O token do bot fornecido pelo BotFather, como 123456:ABC…, em uma única linha | O código QR só aparece se o Telegram aceitar o token. |
TELEGRAM_CHAT_ID | Conversa do Telegram para alertas | Preenchido pelo pareamento via código QR; não digite | O Studio mostra "os alertas vão para a conversa …". |
NEXUS_TELEGRAM_NOTIFY | Alerta do Telegram por falha | true ou false | Um alerta é enviado para cada teste que falha. |
Mais: todas as integrações, o guia de Configurações, solução de problemas. Outros guias: Jira Cloud, Azure Boards, Slack, Microsoft Teams, GitHub Issues.
Ainda com dificuldades? Escreva para [email protected] com a linha exata do erro exibido pelo Studio. Não inclua nenhum token.