> ## Documentation Index > Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt > Use this file to discover all available pages before exploring further. # Eventos dos Webhooks > Receba no seu servidor quando o Telegram enviar, falhar, receber mensagem ou concluir login da conta pessoal. 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](/guides/webhooks/index). Segurança (assinatura HMAC): [Segurança de webhooks](/guides/webhooks/seguranca). *** ## Como vem o POST ```json theme={null} { "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](/guides/webhooks/seguranca). *** ## 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](/guides/webhooks/mensagens-recebidas-e-respostas). ### Login da conta pessoal (`USER`) | 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](/telegram-api/como-funciona/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`. ```json theme={null} { "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" } } ``` Quando o conector expõe confirmação de entrega (mais comum em modo USER). ```json theme={null} { "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" } } ``` ```json theme={null} { "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" } } ``` ```json theme={null} { "event": "telegram.cancelled", "workspaceId": "clxx123...", "instanceId": "clxx456...", "messageId": "clxx789...", "timestamp": "2026-04-11T11:59:00.000Z", "data": { "messageId": "clxx789...", "to": "123456789", "status": "CANCELLED" } } ``` ```json theme={null} { "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" } } ``` ```json theme={null} { "event": "telegram.deleted", "workspaceId": "clxx123...", "instanceId": "clxx456...", "messageId": "clxx789...", "timestamp": "2026-04-11T12:06:00.000Z", "data": { "messageId": "clxx789...", "to": "123456789", "status": "DELETED" } } ``` ```json theme={null} { "event": "telegram.read", "workspaceId": "clxx123...", "instanceId": "clxx456...", "messageId": "clxx789...", "timestamp": "2026-04-11T12:01:00.000Z", "data": { "messageId": "clxx789...", "to": "123456789", "status": "READ" } } ``` Primeiro clique em **link curto** rastreado deste envio. ```json theme={null} { "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" } } ``` ```json theme={null} { "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" } } ``` ```json theme={null} { "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`). ```json theme={null} { "event": "telegram.instance.connecting", "workspaceId": "clxx123...", "instanceId": "clxx456...", "timestamp": "2026-04-11T11:54:00.000Z", "data": { "status": "CONNECTING", "message": "Preparando login por QR" } } ``` ```json theme={null} { "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 } } ``` ```json theme={null} { "event": "telegram.instance.connected", "workspaceId": "clxx123...", "instanceId": "clxx456...", "timestamp": "2026-04-11T11:58:00.000Z", "data": { "status": "ACTIVE" } } ``` ```json theme={null} { "event": "telegram.instance.login_error", "workspaceId": "clxx123...", "instanceId": "clxx456...", "timestamp": "2026-04-11T11:57:00.000Z", "data": { "code": "TIMEOUT", "message": "QR login expired" } } ``` *** ## Próximos passos * [Quick Start](/telegram-api/como-funciona/quick-start) * [Modos de conexão](/telegram-api/como-funciona/modos-de-conexao) * [Introdução](/telegram-api/como-funciona/introducao)