Skip to main content
Telegram é o canal direto no app: avisos rápidos, bots de suporte e conversas sem depender de SMS ou WhatsApp.

​
O que é Telegram na Notifique?

É o jeito de falar com seus clientes no Telegram sem montar infraestrutura do zero. Você conecta um bot (o caminho mais comum) ou, em casos específicos, uma conta pessoal, e passa a:
  • Enviar texto, mídia por URL HTTPS e localização (conforme o modo)
  • Receber mensagens no bot ou na conta e reagir com automação
  • Acompanhar fila, status e falhas pela API ou webhooks
  • Editar ou apagar mensagens já enviadas, quando o Telegram permitir
Pense no bot como um atendente com nome @meubot: previsível, documentado e ideal para produção.
O Telegram Gateway (SMS com código da Meta) é outro produto. Esta documentação é só para mensagens dentro do app Telegram.

​
Bot ou conta pessoal?

Cada instância é ou bot ou conta. Não dá para trocar o modo na mesma linha, se mudar de ideia, crie uma nova. Comparativo completo e quando migrar: Modos de conexão.

​
Regras que todo integrador precisa saber

​
No modo bot (o mais comum)

O Telegram não deixa o bot puxar conversa do nada. Em quase todos os casos:
  1. O usuário precisa falar primeiro, abrir o bot e enviar /start (ou tocar em “Iniciar”).
  2. Só depois o bot pode responder e enviar mensagens naquele chat.
  3. Use GET /v1/telegram/chats para achar chatId e @username de quem já iniciou.
Isso não é limitação do Notifique: é política anti-spam da Bot API do Telegram.

​
No modo conta pessoal

Você age com a identidade da conta. Automatizar DM em massa ou spam pode violar os Termos de Serviço do Telegram. Use só quando o bot não resolver e com responsabilidade. Login com 2FA pode exigir string de sessão em vez de QR.
Eventos de webhook no Telegram começam com telegram.*. No WhatsApp, é message.*. Se usar os dois canais, separe os handlers.

​
Como conectar

  1. Crie uma instância no painel ou API (bot com token ou conta com acceptUserTerms)
  2. No bot, status fica ACTIVE na hora; na conta, a resposta já traz o QR em connection, ou use generateShareableLink: true para enviar o link a outra pessoa
  3. Envie com instanceId, destino (chatId ou @usuario) e tipo de conteúdo
Passo a passo: Quick Start (abas Bot e Conta pessoal).
Cada API Key pertence a um workspace. Na v1 não envie x-workspace-id.

​
Comparativo: o que cada modo faz

* Conta pessoal tem mais liberdade, mas não é licença para spam. Respeite ToS e opt-in.

​
Ciclo da mensagem

Depois do POST, a mensagem passa por QUEUED ou SCHEDULED, depois SENT ou FAILED. Engajamento (READ, RESPONDED, etc.) pode chegar depois via webhook. SENT significa que o Telegram aceitou, não que a pessoa leu. OTP e alertas urgentes podem usar "options": { "priority": "high" }. Não abuse em campanha em massa.

​
Depois de conectar

  • Envie pelo painel ou POST /v1/telegram/messages
  • Liste chats e inbound para montar atendimento
  • Configure webhooks (telegram.sent, telegram.received, …)
  • Restrinja a chave com instanceIds e escopos mínimos

​
Próximos passos