Eventos de Webhook

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. Seguridad (firma HMAC): Seguridad de Webhook.

Cómo se ve el 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	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.

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.

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 (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.

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

Cuando el conector expone confirmación de entrega (más común en 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": "Corrected text"
  }
}

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

Primer clic en un short link rastreado de este envío.

{
  "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": "Customer reply",
    "status": "RESPONDED"
  }
}

telegram.received

{
  "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).

telegram.instance.connecting

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

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 de Webhook

En resumen

Cómo se ve el POST

Qué debe devolver su servidor

Referencia de eventos

Mensajes que usted envía

Mensajes que usted recibe

Payload por evento

Próximos pasos

​En resumen

​Cómo se ve el POST

​Qué debe devolver su servidor

​Referencia de eventos

​Mensajes que usted envía

​Mensajes que usted recibe

​Login de cuenta personal (USER)

​Payload por evento

​Próximos pasos

En resumen

Cómo se ve el POST

Qué debe devolver su servidor

Referencia de eventos

Mensajes que usted envía

Mensajes que usted recibe

Login de cuenta personal (`USER`)

Payload por evento

Próximos pasos