> ## 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 de Webhook > Reciba en su servidor notificación cuando Telegram envía, falla, recibe un mensaje o completa el login de cuenta personal. Con la API usted **pregunta**; con webhooks Notifique **notifica**. En Telegram los nombres son **`telegram.*`**, no los confunda con WhatsApp `message.*`. ## En resumen * Cada entrega es un **POST** `application/json` a su URL registrada. * Los eventos `telegram.*` son **solo Telegram** (WhatsApp usa `message.*`). * El modo **cuenta personal** también dispara `telegram.instance.*` durante el login. * Habilite **solo** los eventos que necesite su integración. * Responda **2xx rápido**; el trabajo pesado va a una cola de su lado. Configuración general: [Webhooks](/es/guides/webhooks/index). Seguridad (firma HMAC): [Seguridad de Webhook](/es/guides/webhooks/seguranca). *** ## Cómo se ve el 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 | Descripción | | ------------- | --------------------------------------- | | `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`. *** ## Qué debe devolver su servidor | Respuesta | Efecto | | ----------------------- | ------------------------------------ | | **2xx** within \~10s | Event delivered; removed from queue | | **4xx / 5xx / timeout** | Automatic retry (5 min, 30 min, 2 h) | Valide `X-Notifique-Signature` y un timestamp reciente. Detalles: [Seguridad de Webhook](/es/guides/webhooks/seguranca). *** ## Referencia de eventos ### Mensajes que usted envía | Evento | Cuándo se dispara | Qué hacer con él | | -------------------- | ----------------------------------------- | ------------------- | | `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 | ### Mensajes que usted recibe | Evento | Cuándo se dispara | Qué hacer con él | | ------------------- | --------------------------------------------- | --------------------- | | `telegram.received` | **Someone sent** a message to the bot/account | Bot, support, keyword | Los entrantes solo se disparan si están habilitados en **Settings → Received messages → Telegram**. Guía: [Mensajes recibidos](/es/guides/webhooks/mensagens-recebidas-e-respostas). ### Login de cuenta personal (`USER`) | Evento | Cuándo se dispara | Qué hacer con él | | ------------------------------- | --------------------------------- | ------------------ | | `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 | En [Inicio rápido](/es/telegram-api/como-funciona/quick-start) (pestaña **Cuenta personal**), puede usar `telegram.instance.qrcode` en lugar de polling del QR. *** ## Payload por evento Cuerpo POST completo. El sobre (`event`, ids, `timestamp`) coincide con el ejemplo anterior; abajo cambia lo de `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" } } ``` Cuando el conector expone confirmación de entrega (más común en 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": "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" } } ``` Primer clic en un **short link rastreado** de este envío. ```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" } } ``` En modo **USER**, algunos campos pueden diferir (ej.: sin `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" } } ``` *** ## Próximos pasos * [Inicio rápido](/es/telegram-api/como-funciona/quick-start) * [Modos de conexión](/es/telegram-api/como-funciona/modos-de-conexao) * [Introducción](/es/telegram-api/como-funciona/introducao)