Eventos dos Webhooks

Na API você pergunta; no webhook a Notifique avisa. No Telegram os nomes são telegram.*, não confunda com message.* do WhatsApp.

Em poucas palavras

Toda entrega é um POST application/json para a URL cadastrada.
Eventos telegram.* são só Telegram (WhatsApp usa message.*).
Modo conta pessoal também dispara telegram.instance.* durante o login.
Ative só os eventos que sua integração usa.
Responda 2xx rápido; trabalho pesado vai para fila no seu lado.

Configuração geral: Webhooks. Segurança (assinatura HMAC): Segurança de webhooks.

Como vem o POST

{
  "event": "telegram.sent",
  "workspaceId": "clxx123...",
  "instanceId": "clxx456...",
  "messageId": "clxx789...",
  "timestamp": "2026-04-11T12:00:00.000Z",
  "data": {
    "to": "123456789",
    "type": "TEXT",
    "status": "SENT",
    "sentAt": "2026-04-11T12:00:00.000Z",
    "externalId": "42"
  }
}

Campo	Descrição
`event`	Nome do evento (ex.: `telegram.sent`)
`workspaceId`	ID do workspace
`instanceId`	ID da conexão Telegram (bot ou conta)
`messageId`	ID da mensagem enviada (quando aplicável)
`timestamp`	ISO 8601, use para anti-replay
`data`	Campos específicos do evento

Headers: X-Notifique-Signature, X-Notifique-Timestamp, X-Workspace-Id, X-Webhook-Event.

O que seu servidor deve responder

Resposta	Efeito
2xx em até ~10s	Evento entregue; sai da fila
4xx / 5xx / timeout	Retentativa automática (5 min, 30 min, 2 h)

Valide X-Notifique-Signature e timestamp recente. Detalhes: Segurança de webhooks.

Referência por evento

Mensagens que você envia

Evento	Quando dispara	O que fazer com isso
`telegram.sent`	Telegram aceitou a mensagem	Marcar como enviado
`telegram.delivered`	Entrega registrada (quando disponível)	Confirmar entrega
`telegram.failed`	Falha após tentativas	Alertar / retentar
`telegram.cancelled`	Agendamento ou fila cancelados	Atualizar status
`telegram.edited`	Texto alterado via API	Sincronizar conteúdo
`telegram.deleted`	Mensagem apagada no chat	Atualizar histórico
`telegram.read`	Leitura registrada (mais comum em USER)	Métricas
`telegram.clicked`	Primeiro clique em link curto do envio	Campanha
`telegram.responded`	Destinatário respondeu à sua mensagem	Fluxo conversacional

Mensagens que você recebe

Evento	Quando dispara	O que fazer com isso
`telegram.received`	Alguém mandou mensagem ao bot/conta	Bot, atendimento, keyword

Inbound só dispara se estiver ligado em Settings → Received messages → Telegram. Guia: Mensagens recebidas.

Evento	Quando dispara	O que fazer com isso
`telegram.instance.connecting`	Preparando QR / login	UI “conectando…”
`telegram.instance.qrcode`	Novo QR ou link `tg://login`	Mostrar QR na sua UI
`telegram.instance.connected`	Sessão salva, ACTIVE	Liberar envios
`telegram.instance.login_error`	Falha (timeout, 2FA, cancelado)	Alertar usuário

No Quick Start (aba Conta pessoal), você pode usar telegram.instance.qrcode em vez de polling no QR.

Payload de cada evento

Corpo completo do POST. O envelope (event, ids, timestamp) segue o exemplo acima; abaixo, o que muda em data.

telegram.sent

{
  "event": "telegram.sent",
  "workspaceId": "clxx123...",
  "instanceId": "clxx456...",
  "messageId": "clxx789...",
  "timestamp": "2026-04-11T12:00:00.000Z",
  "data": {
    "to": "123456789",
    "type": "TEXT",
    "status": "SENT",
    "sentAt": "2026-04-11T12:00:00.000Z",
    "externalId": "42"
  }
}

telegram.delivered

Quando o conector expõe confirmação de entrega (mais comum em modo USER).

{
  "event": "telegram.delivered",
  "workspaceId": "clxx123...",
  "instanceId": "clxx456...",
  "messageId": "clxx789...",
  "timestamp": "2026-04-11T12:00:05.000Z",
  "data": {
    "messageId": "clxx789...",
    "to": "123456789",
    "status": "DELIVERED",
    "deliveredAt": "2026-04-11T12:00:05.000Z"
  }
}

telegram.failed

{
  "event": "telegram.failed",
  "workspaceId": "clxx123...",
  "instanceId": "clxx456...",
  "messageId": "clxx789...",
  "timestamp": "2026-04-11T12:00:05.000Z",
  "data": {
    "to": "123456789",
    "status": "FAILED",
    "errorMessage": "chat_not_found"
  }
}

telegram.cancelled

{
  "event": "telegram.cancelled",
  "workspaceId": "clxx123...",
  "instanceId": "clxx456...",
  "messageId": "clxx789...",
  "timestamp": "2026-04-11T11:59:00.000Z",
  "data": {
    "messageId": "clxx789...",
    "to": "123456789",
    "status": "CANCELLED"
  }
}

telegram.edited

{
  "event": "telegram.edited",
  "workspaceId": "clxx123...",
  "instanceId": "clxx456...",
  "messageId": "clxx789...",
  "timestamp": "2026-04-11T12:05:00.000Z",
  "data": {
    "messageId": "clxx789...",
    "to": "123456789",
    "status": "EDITED",
    "newContent": "Texto corrigido"
  }
}

telegram.deleted

{
  "event": "telegram.deleted",
  "workspaceId": "clxx123...",
  "instanceId": "clxx456...",
  "messageId": "clxx789...",
  "timestamp": "2026-04-11T12:06:00.000Z",
  "data": {
    "messageId": "clxx789...",
    "to": "123456789",
    "status": "DELETED"
  }
}

telegram.read

{
  "event": "telegram.read",
  "workspaceId": "clxx123...",
  "instanceId": "clxx456...",
  "messageId": "clxx789...",
  "timestamp": "2026-04-11T12:01:00.000Z",
  "data": {
    "messageId": "clxx789...",
    "to": "123456789",
    "status": "READ"
  }
}

telegram.clicked

Primeiro clique em link curto rastreado deste envio.

{
  "event": "telegram.clicked",
  "workspaceId": "clxx123...",
  "instanceId": "clxx456...",
  "messageId": "clxx789...",
  "timestamp": "2026-04-11T12:02:00.000Z",
  "data": {
    "messageId": "clxx789...",
    "to": "123456789",
    "status": "CLICKED",
    "clickedAt": "2026-04-11T12:02:00.000Z"
  }
}

telegram.responded

{
  "event": "telegram.responded",
  "workspaceId": "clxx123...",
  "instanceId": "clxx456...",
  "messageId": "clxx789...",
  "timestamp": "2026-04-11T12:03:00.000Z",
  "data": {
    "messageId": "clxx789...",
    "replyText": "Resposta do destinatário",
    "status": "RESPONDED"
  }
}

telegram.received

{
  "event": "telegram.received",
  "workspaceId": "clxxworkspace",
  "instanceId": "clxxinstance",
  "timestamp": "2026-04-11T12:01:00.000Z",
  "data": {
    "inboundId": "clxxinbound",
    "persisted": true,
    "preview": "Oi, preciso de ajuda",
    "chatId": "123456789",
    "fromUsername": "cliente"
  }
}

No modo USER, alguns campos podem vir diferentes (ex.: sem fromUsername).

telegram.instance.connecting

{
  "event": "telegram.instance.connecting",
  "workspaceId": "clxx123...",
  "instanceId": "clxx456...",
  "timestamp": "2026-04-11T11:54:00.000Z",
  "data": {
    "status": "CONNECTING",
    "message": "Preparando login por QR"
  }
}

telegram.instance.qrcode

{
  "event": "telegram.instance.qrcode",
  "workspaceId": "clxx123...",
  "instanceId": "clxx456...",
  "timestamp": "2026-04-11T11:55:00.000Z",
  "data": {
    "loginUrl": "tg://login?token=...",
    "base64": "data:image/png;base64,...",
    "expiresInSec": 120
  }
}

telegram.instance.connected

{
  "event": "telegram.instance.connected",
  "workspaceId": "clxx123...",
  "instanceId": "clxx456...",
  "timestamp": "2026-04-11T11:58:00.000Z",
  "data": {
    "status": "ACTIVE"
  }
}

{
  "event": "telegram.instance.login_error",
  "workspaceId": "clxx123...",
  "instanceId": "clxx456...",
  "timestamp": "2026-04-11T11:57:00.000Z",
  "data": {
    "code": "TIMEOUT",
    "message": "QR login expired"
  }
}

API Telegram

Eventos dos Webhooks

Em poucas palavras

Como vem o POST

O que seu servidor deve responder

Referência por evento

Mensagens que você envia

Mensagens que você recebe

Payload de cada evento

Próximos passos

​Em poucas palavras

​Como vem o POST

​O que seu servidor deve responder

​Referência por evento

​Mensagens que você envia

​Mensagens que você recebe

​Login da conta pessoal (USER)

​Payload de cada evento

​Próximos passos

Em poucas palavras

Como vem o POST

O que seu servidor deve responder

Referência por evento

Mensagens que você envia

Mensagens que você recebe

Login da conta pessoal (`USER`)

Payload de cada evento

Próximos passos