Skip to main content
Esta página é para quem vai integrar envio Telegram (e leituras simples) ao Notifique. Se você só usa o painel, dá para cadastrar o bot e testar por lá; a API é para site, CRM ou automação.

​
Antes de começar

Você vai precisar de:
  • Uma chave de API com as permissões que for usar (enviar, listar, cancelar, editar, apagar, instâncias, chats, inbound — veja escopos).
  • Autenticação: Authorization: Bearer sk_live_... ou x-api-key.
  • URL base (ex.: https://api.notifique.dev).
Para bot, crie um bot no @BotFather e guarde o token.

​
O caminho em três passos

  1. Criar a conexão (instância) em modo BOT com o token.
  2. Listar instâncias e copiar o instanceId.
  3. Enviar mensagem — a pessoa costuma precisar ter falado com o bot antes (ou estar em grupo onde o bot pode responder).
Depois você evolui para mídia, agendamento e webhooks.

​
1. Criar uma conexão (bot)

Pedido 
POST /v1/telegram/instances
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "Meu atendimento",
  "mode": "BOT",
  "botToken": "SEU_TOKEN"
}
Se o token estiver errado, a API devolve erro claro. Se estiver certo, a conexão fica pronta para enviar.

​
1b. Modo USER — “parear” com QR pela API

Só quando o seu caso realmente precisar de conta em vez de bot:
  1. POST /v1/telegram/instances com mode: "USER" e acceptUserTerms: true (mesmos termos/riscos do painel).
  2. Consultar GET /v1/telegram/instances/{id}/qr até o status ficar ACTIVE (ou tratar ERROR). Enquanto conecta: CONNECTING; com QR novo: WAITING_QR com loginUrl e imagem em base64. Abra o link no app Telegram no celular ou escaneie o QR.
  3. Opcional: POST /v1/telegram/instances/{id}/qr/cancel aborta o fluxo iniciado por esta API.
  4. Alternativa ao QR: POST /v1/telegram/instances/{id}/session com sessionString (ex.: exportada do GramJS).
No painel, marque webhooks como telegram.instance.connecting, telegram.instance.qrcode, telegram.instance.connected, telegram.instance.login_error se quiser acompanhar. 409 em GET .../qr costuma significar que outro fluxo de login já está aberto (ex.: tela do painel com SSE). Mais leitura: Modo BOT e modo USER e ciclo de vida da instância.

​
2. Listar conexões

Pedido 
GET /v1/telegram/instances?page=1&limit=20
Authorization: Bearer sk_live_xxxxx
Guarde o id da instância para os próximos passos.

​
3. Enviar uma mensagem de texto

O destinatário em geral precisa ter iniciado conversa com o bot (ou estar em contexto onde o bot pode falar). Pedido 
POST /v1/telegram/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "instanceId": "clxx...",
  "to": ["123456789"],
  "type": "text",
  "payload": { "message": "Olá! Teste pelo Notifique." }
}
A resposta traz ids das mensagens e se ficou na fila ou agendada. Extras: em options — priority (high usa fila dedicada Telegram + webhooks prioritários), webhook (url + secret opcional) só para aquele envio, maxRetries; no corpo, metadata (texto→texto). Detalhe completo no OpenAPI, rota POST /v1/telegram/messages.

​
4. Ver o que já foi enviado

Pedido 
GET /v1/telegram/messages?page=1&limit=20
Authorization: Bearer sk_live_xxxxx
Filtros úteis (opcional): instanceIds, status, type, fromDate / toDate.

​
5. Ver uma mensagem só

Pedido 
GET /v1/telegram/messages/clxx_id_da_mensagem
Authorization: Bearer sk_live_xxxxx

​
6. Cancelar (fila ou agendamento)

Só enquanto ainda não saiu de vez. Pedido 
POST /v1/telegram/messages/clxx_id/cancel
Authorization: Bearer sk_live_xxxxx
Pode gerar webhook telegram.cancelled se estiver configurado.

​
7. Corrigir texto depois de enviado

Só para mensagem de texto, dentro do que o Telegram permitir. Pedido 
PATCH /v1/telegram/messages/clxx_id/edit
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{ "text": "Texto corrigido" }

​
8. Apagar no chat (“apagar para todos”)

Depende das regras do Telegram (tempo, tipo de chat, etc.). Pedido 
DELETE /v1/telegram/messages/clxx_id
Authorization: Bearer sk_live_xxxxx

​
9. Listar quem falou com o bot (/start, etc.)

Útil para achar chatId e username. Pedido 
GET /v1/telegram/chats?page=1&limit=20&instanceId=clxx_inst
Authorization: Bearer sk_live_xxxxx
Query opcional: q (busca), status (active, left, …).

​
10. Ver mensagens recebidas no bot

Pedido 
GET /v1/telegram/messages/inbound?page=1&limit=20
Authorization: Bearer sk_live_xxxxx
Detalhe de um registro: 
GET /v1/telegram/messages/inbound/clxx_id
Authorization: Bearer sk_live_xxxxx
Quando alguém manda mensagem, você pode receber também telegram.received. Em Configurações → Canais → Telegram, escolha se quer guardar, webhook ou os dois para mensagens recebidas.

​
11. Webhooks

Cadastre eventos como telegram.sent, telegram.failed, telegram.received, etc. Não espere message.sent para Telegram — esse padrão é do WhatsApp. Formato geral do corpo: veja eventos WhatsApp como referência de estrutura; nomes específicos do Telegram: eventos Telegram.

​
Resumo rápido

ObjetivoCaminho
Listar enviadosGET /v1/telegram/messages
Detalhe enviadoGET /v1/telegram/messages/:id
Listar chatsGET /v1/telegram/chats
Listar recebidosGET /v1/telegram/messages/inbound
Detalhe recebidoGET /v1/telegram/messages/inbound/:id
EnviarPOST /v1/telegram/messages
CancelarPOST /v1/telegram/messages/:id/cancel
Editar textoPATCH /v1/telegram/messages/:id/edit
ApagarDELETE /v1/telegram/messages/:id

​
Continuar