Skip to main content

​
O fluxo principal (visão geral)

  1. Criar instância em modo BOT com o token do @BotFather.
  2. Listar instâncias e copiar o instanceId.
  3. Enviar mensagem com POST /v1/telegram/messages — o usuário precisa ter falado com o bot antes (ou estar em grupo permitido).
Depois você pode evoluir para mídia, agendamento e webhooks telegram.* (passos adiante nesta página).

​
Antes de começar

  • Uma chave de API com as permissões que você for usar (enviar, ler, cancelar, editar, apagar, instâncias).
  • Envie a chave em todo pedido:
    Authorization: Bearer sk_live_... ou cabeçalho x-api-key.

​
1. Criar uma conexão (bot)

Crie um bot com o @BotFather, copie o token e envie: 
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 responde com erro claro. Se estiver certo, a conexão já fica pronta para enviar.

​
1b. Modo USER — QR pela API (como “parear” pelo celular)

  1. POST /v1/telegram/instances com mode: "USER" e acceptUserTerms: true (mesmo risco/termos do painel).
  2. Polling: GET /v1/telegram/instances/{id}/qr até status ser ACTIVE (ou tratar ERROR).
    • Enquanto conecta: CONNECTING.
    • Com QR novo: WAITING_QR + loginUrl (tg://...) e base64 (imagem PNG, estilo WhatsApp).
    • Abra o link no app Telegram no celular ou escaneie o QR gerado a partir do base64.
  3. Opcional: POST /v1/telegram/instances/{id}/qr/cancel aborta só o fluxo iniciado pela API (não mata o stream do dashboard).
  4. Alternativa ao QR: POST /v1/telegram/instances/{id}/session com sessionString exportada do GramJS.
Webhooks (marque no painel): telegram.instance.connecting, telegram.instance.qrcode, telegram.instance.connected, telegram.instance.login_error. 409 em GET .../qr = outro cliente já está no fluxo (ex.: tela do dashboard com SSE).

​
2. Listar conexões

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 precisa ter falado com o bot antes (ou estar em um grupo onde o bot pode mandar mensagem). 
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 internos das mensagens e se ficou na fila ou agendada.

​
4. Ver o que já foi enviado

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

​
5. Ver uma mensagem só

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

​
6. Cancelar envio (fila ou agendamento)

Só funciona enquanto ainda não saiu de vez. 
POST /v1/telegram/messages/clxx_id/cancel
Authorization: Bearer sk_live_xxxxx
Dispara o webhook telegram.cancelled (se você marcou esse evento).

​
7. Editar texto depois de enviado

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

{ "text": "Texto corrigido" }
Dispara telegram.edited quando configurado.

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

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

​
9. Ver o que chegou no bot

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 para o bot, você também pode receber o webhook telegram.received (além de guardar o histórico aqui).

​
10. Webhooks

Cadastre no painel os eventos telegram.sent, telegram.failed, telegram.received, etc.
Não espere message.sent para Telegram — esse nome é só WhatsApp. Mais detalhes: Eventos dos Webhooks (WhatsApp) (formato do corpo) e Eventos Telegram.

​
Resumo

ObjetivoMétodo e caminho
Listar enviadosGET /v1/telegram/messages
Detalhe enviadoGET /v1/telegram/messages/:id
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

​
Referências