Skip to main content
Escolher o modo é como escolher atendente com crachá (bot) ou sua própria voz (conta): o bot é o caminho recomendado; a conta pessoal é exceção com mais responsabilidade.

​
Bot ou conta pessoal?

Cada instância Telegram no Notifique usa um dos dois modos. Não dá para alternar na mesma linha: se precisar mudar, crie uma nova.

​
Quando usar o bot

  • Atendimento, OTP, confirmações e automações explícitas
  • Fluxo alinhado à Bot API (documentada e estável)
  • Você quer que o cliente fale com @meubot, não com uma pessoa

​
Quando usar conta pessoal

  • O bot não atende o caso de uso (fluxo legado, atuar como pessoa em chat específico)
  • Você aceita os termos (acceptUserTerms: true) e o risco de violar ToS se abusar
Automatizar conta de usuário para spam ou DM em massa viola os Termos do Telegram e pode resultar em banimento. Prefira bot sempre que possível.

​
Regra de ouro do bot: o usuário fala primeiro

Na Bot API, o Telegram bloqueia mensagem “fria” do bot para quem nunca interagiu.
  1. O destinatário abre o bot e envia /start (ou toca em Iniciar).
  2. O Notifique registra o chat (webhook + lista em GET /v1/telegram/chats).
  3. Aí sim você envia com chatId ou @username em to.
Se tentar enviar antes, a API pode falhar com erro de chat inválido ou bloqueio, comportamento esperado do Telegram.
Em grupos e canais as regras variam (bot precisa ser admin ou membro). Para DM 1 a 1, trate /start como parte do onboarding do seu produto.

​
Modo bot em detalhe

Como conectar
  1. Crie o bot no @BotFather e copie o token.
  2. POST /v1/telegram/instances com mode: "BOT" e botToken.
  3. O Notifique valida o token e configura o webhook do bot.
  4. Status ACTIVE, pode enviar (para quem já iniciou conversa).
O que o bot faz bem
  • Inbound previsível (telegram.received)
  • Lista de chats (GET /v1/telegram/chats)
  • Localização (type: location) no envio
  • Identidade clara para o usuário final
Limitações
  • Não “puxa” conversa sem /start
  • Recursos limitados ao que a Bot API expõe
  • Não é sua conta pessoal

​
Modo conta pessoal em detalhe

Como conectar
  1. POST /v1/telegram/instances com mode: "USER" e acceptUserTerms: true.
  2. A resposta traz o QR em connection (como no WhatsApp não oficial), exiba base64 ou abra loginUrl.
  3. Opcional: generateShareableLink: true na criação, ou POST .../connect-page/enable depois, para repassar hostedUrl a outra pessoa.
  4. QR expirou? GET /v1/telegram/instances/:id/qr ou webhook telegram.instance.qrcode.
  5. Alternativa: POST .../session com sessionString (útil com 2FA).
  6. Recupere ou invalide o link: GET/POST .../connect-page (status, enable, rotate-secret, disable).
Integrando só pela API (sem browser no servidor)? Use generateShareableLink: true em POST /v1/telegram/instances ou habilite depois com POST .../connect-page/enable. Detalhes no Quick Start.
Cuidados
  • Login com senha 2FA no QR pode não funcionar, use sessão manual.
  • 409 ao pedir QR: outro fluxo de login já aberto (ex.: painel com SSE).
  • Enquanto PENDING, envio não funciona.
Conta pessoal é como emprestar sua identidade ao sistema. Use só quando o bot não resolver.

​
Comparativo completo

* Mais liberdade não substitui opt-in e ToS.

​
Webhooks por modo

Lista e payloads: Eventos dos webhooks.

​
Próximos passos