Skip to main content
Importante: Os “bots” do Telegram são contas especiais controladas por um token, não por um número de telefone. Um único bot pode ser adicionado a vários grupos ou canais, mas cada mensagem deve chegar ao bot (por meio de uma menção direta, resposta ou postagem no canal) para que a IA responda.

​
🔢 Índice

  1. Create a Telegram Bot with BotFather
  2. Retrieve the Bot HTTP Token
  3. Add & Promote the Bot in Chats / Channels
  4. Configure Webhooks in Telegram
  5. Connect Your Bot to ZappWay
  6. Send a Test Message
  7. Monitoring & Maintenance

​
1. Crie um bot de telegrama com BotFather

  1. Open Telegram (desktop or mobile).
  2. Search for @BotFather and open the verified account.
  3. Tap Start (or send /start). BotFather displays a menu of commands.
  4. Send /newbot.
  5. Follow the prompts:
  • Nome do bot – o nome de exibição completo mostrado aos usuários (por exemplo, “Suporte ZappWay”).
    • Nome de usuário – deve terminar com bot (por exemplo, zappway_support_bot).
  1. BotFather responde com:
✅ Copie o token – você irá colá-lo no ZappWay mais tarde.
Dica: Seu bot é público por padrão. Se preferir ocultá-lo da pesquisa, envie /setprivate para BotFather.

​
2. Recuperar o token HTTP do bot

  • Se você perdeu o token, abra o BotFather e envie /token, depois escolha seu bot.
  • Armazene o token com segurança (gerenciador de senhas, cofre); qualquer pessoa com este token pode controlar o bot.

​
3. Adicione e promova o bot em chats/canais

​
3.1 Chat de suporte privado (opcional)

  1. Open a 1-on-1 chat with your bot.
  2. Send /start so the bot is allowed to message you.

​
3.2 Bate-papo de suporte em grupo

  1. Create or open the group where customers will send messages.
  2. Tap the group title ➜ Add Member ➜ search your bot’s username ➜ Add.
  3. Promote it to Administrator (required so it can read and send all messages).
  • Permissões necessárias: Ler mensagens, Enviar mensagens, Gerenciar mensagens (opcional).

​
3.3 Canal Público ou Privado

  1. Open the channel ➜ Manage ➜ Administrators ➜ Add Admin ➜ select your bot.
  2. Grant Post Messages permission so the AI can publish replies.
Por que administrador? O Telegram só entrega todas as mensagens para bots que são administradores; caso contrário, o bot verá apenas menções.

​
4. Configurar Webhooks no Telegram

O Telegram fornece atualizações para um URL de webhook por bot.
  1. Copy the Callback URL and Verify Token shown in ZappWay (you will get them in Step 5).
  2. Send this HTTPS request (you can use a browser address bar):
  • Substitua <YOUR_TOKEN>, <CALLBACK_URL>, <VERIFY_TOKEN> por valores reais.
  • O Telegram responde com {"ok":true, "result":true, ...} se o webhook estiver definido.
Nota:
  • A URL deve usar HTTPS com um certificado válido.
  • Um único bot pode apontar para um webhook por vez. Chamar setWebhook novamente substitui o URL anterior.

​
5. Conecte seu bot ao ZappWay

  1. Sign in to ZappWay ➜ Integrations ➜ Telegram ➜ Add Telegram Integration.
  2. Paste the HTTP Token you copied from BotFather. Click Continue.
  • ZappWay valida o token com o endpoint getMe do Telegram.
  1. ZappWay now displays two read-only fields:
  • URL de retorno de chamada – o endpoint que você acabou de definir na Etapa 4
    • Token de verificação – o secret_token que você passou para setWebhook
  1. Click Save. The integration status changes to “Waiting for updates”.
Se o ZappWay mostrar “Credenciais inválidas”, verifique novamente o token no BotFather e repita a Etapa 5.

​
6. Envie uma mensagem de teste

  1. From any Telegram account, send “Hello” to:
  • o bot diretamente ou
    • um grupo/canal onde o bot é administrador.
  1. No ZappWay ➜ Caixa de entrada, você deverá ver a mensagem recebida.
  2. Se você configurou fluxos de resposta automática, o funcionário de IA deverá responder automaticamente.
Solução de problemas: Nenhuma mensagem na Caixa de entrada?
  • Confirme o status do webhook com https://api.telegram.org/bot<YOUR_TOKEN>/getWebhookInfo.
  • last_error_message revelará problemas de SSL ou de rede.
  • Certifique-se de que o bot tenha permissão para ler mensagens de grupo/canal (função de administrador).

​
7. Monitoramento e Manutenção

​
7.1 Saúde do webhook

  • getWebhookInfo retorna os campos pending_update_count e last_error_date/message.
  • Um last_error_date diferente de zero significa que o Telegram não conseguiu POST no ZappWay. Verifique firewall/SSL.

​
7.2 Segurança de token

  • Os tokens nunca expiram automaticamente, mas os revogam imediatamente se vazarem: Comando /revoke no BotFather ➜ Requer a configuração de um novo webhook.

​
7.3 Escala e Limites

  • Os bots do Telegram podem enviar 30 mensagens/segundo no geral e 1 mensagem/segundo por chat.
  • Anexos grandes (vídeos, documentos) são entregues como IDs de arquivo; ZappWay busca conteúdo sob demanda.

​
7.4 Erros Comuns

​
✅ Notas Finais

  • Um webhook por bot – se você experimentar a preparação, lembre-se de voltar para o URL de produção.
  • Modo de privacidade – por padrão, os bots não veem todas as mensagens do grupo. A promoção do administrador desativa o modo de privacidade para que a IA possa ler o contexto completo.
  • Testes – Sempre teste primeiro em um chat privado, depois em um pequeno grupo, antes de lançar em canais públicos.
  • Segurança – Nunca compartilhe seu token em capturas de tela ou registros.
Siga todas as etapas acima e sua integração do Telegram com o ZappWay estará ativa e pronta para lidar com as conversas dos clientes automaticamente.