> ## 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. # Webhook Events > Get notified on your server when Telegram sends, fails, receives a message, or completes personal account login. With the API you **ask**; with webhooks Notifique **notifies**. On Telegram names are **`telegram.*`**, do not confuse with WhatsApp `message.*`. ## In brief * Every delivery is a **POST** `application/json` to your registered URL. * `telegram.*` events are **Telegram only** (WhatsApp uses `message.*`). * **Personal account** mode also fires `telegram.instance.*` during login. * Enable **only** the events your integration needs. * Reply **2xx quickly**; heavy work goes to a queue on your side. General setup: [Webhooks](/en/guides/webhooks/index). Security (HMAC signature): [Webhook security](/en/guides/webhooks/seguranca). *** ## How the POST looks ```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" } } ``` | Field | Description | | ------------- | --------------------------------------- | | `event` | Event name (e.g. `telegram.sent`) | | `workspaceId` | Workspace ID | | `instanceId` | Telegram connection ID (bot or account) | | `messageId` | Sent message ID (when applicable) | | `timestamp` | ISO 8601, use for anti-replay | | `data` | Event-specific fields | Headers: `X-Notifique-Signature`, `X-Notifique-Timestamp`, `X-Workspace-Id`, `X-Webhook-Event`. *** ## What your server should return | Response | Effect | | ----------------------- | ------------------------------------ | | **2xx** within \~10s | Event delivered; removed from queue | | **4xx / 5xx / timeout** | Automatic retry (5 min, 30 min, 2 h) | Validate `X-Notifique-Signature` and a recent timestamp. Details: [Webhook security](/en/guides/webhooks/seguranca). *** ## Event reference ### Messages you send | Event | When it fires | What to do with it | | -------------------- | ----------------------------------------- | ------------------- | | `telegram.sent` | Telegram accepted the message | Mark as sent | | `telegram.delivered` | Delivery recorded (when available) | Confirm delivery | | `telegram.failed` | Failed after retries | Alert / retry | | `telegram.cancelled` | Schedule or queue cancelled | Update status | | `telegram.edited` | Text changed via API | Sync content | | `telegram.deleted` | Message deleted in chat | Update history | | `telegram.read` | Read receipt (more common in USER) | Metrics | | `telegram.clicked` | First click on a short link from the send | Campaign | | `telegram.responded` | Recipient replied to your message | Conversational flow | ### Messages you receive | Event | When it fires | What to do with it | | ------------------- | --------------------------------------------- | --------------------- | | `telegram.received` | **Someone sent** a message to the bot/account | Bot, support, keyword | Inbound only fires if enabled under **Settings → Received messages → Telegram**. Guide: [Inbound messages](/en/guides/webhooks/mensagens-recebidas-e-respostas). ### Personal account login (`USER`) | Event | When it fires | What to do with it | | ------------------------------- | --------------------------------- | ------------------ | | `telegram.instance.connecting` | Preparing QR / login | “Connecting…” UI | | `telegram.instance.qrcode` | New QR or `tg://login` link | Show QR in your UI | | `telegram.instance.connected` | Session saved, **ACTIVE** | Enable sends | | `telegram.instance.login_error` | Failure (timeout, 2FA, cancelled) | Alert user | In [Quick Start](/en/telegram-api/como-funciona/quick-start) (**Personal account** tab), you can use `telegram.instance.qrcode` instead of polling QR. *** ## Payload per event Full POST body. The envelope (`event`, ids, `timestamp`) matches the example above; below is what changes in `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" } } ``` When the connector exposes delivery confirmation (more common in USER mode). ```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": "Corrected text" } } ``` ```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" } } ``` First click on a **tracked short link** from this send. ```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": "Customer reply", "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": "Hi, I need help", "chatId": "123456789", "fromUsername": "customer" } } ``` In **USER** mode, some fields may differ (e.g. no `fromUsername`). ```json theme={null} { "event": "telegram.instance.connecting", "workspaceId": "clxx123...", "instanceId": "clxx456...", "timestamp": "2026-04-11T11:54:00.000Z", "data": { "status": "CONNECTING", "message": "Preparing QR login" } } ``` ```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" } } ``` *** ## Next steps * [Quick Start](/en/telegram-api/como-funciona/quick-start) * [Connection modes](/en/telegram-api/como-funciona/modos-de-conexao) * [Introduction](/en/telegram-api/como-funciona/introducao)