Webhook Events

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. Security (HMAC signature): Webhook security.

How the POST looks

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

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.

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

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

When the connector exposes delivery confirmation (more common in USER mode).

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

First click on a tracked short link from this send.

{
  "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"
  }
}

In USER mode, some fields may differ (e.g. no 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"
  }
}

Telegram API

In brief

How the POST looks

What your server should return

Event reference

Messages you send

Messages you receive

Payload per event

Next steps

​In brief

​How the POST looks

​What your server should return

​Event reference

​Messages you send

​Messages you receive

​Personal account login (USER)

​Payload per event

​Next steps

In brief

How the POST looks

What your server should return

Event reference

Messages you send

Messages you receive

Personal account login (`USER`)

Payload per event

Next steps