Skip to main content

Events Reference

All webhook payloads share this envelope:

{
  "event": "<event-type>",
  "delivery_id": "<string>",
  "data": { ... }
}

message.received​

Fires when a new inbound message arrives.

{
  "event": "message.received",
  "delivery_id": "12345",
  "data": {
    "thread_id": "telegram:123456789",
    "message_id": "msg_abc123",
    "channel": "telegram",
    "text": "Hello, I need help with my order",
    "from": { "id": "123456789", "name": "Alice Smith" },
    "timestamp": "2026-03-11T10:00:00Z"
  }
}

message.updated​

Fires when a message is edited.

{
  "event": "message.updated",
  "delivery_id": "12346",
  "data": {
    "thread_id": "telegram:123456789",
    "message_id": "msg_abc123",
    "channel": "telegram",
    "new_text": "Hello, I need help with my order (edited)"
  }
}

message.deleted​

Fires when a message is deleted.

{
  "event": "message.deleted",
  "delivery_id": "12347",
  "data": {
    "thread_id": "telegram:123456789",
    "message_id": "msg_abc123",
    "channel": "telegram"
  }
}

conversation.started​

Fires when a new conversation thread is created.

{
  "event": "conversation.started",
  "delivery_id": "12348",
  "data": {
    "thread_id": "telegram:123456789",
    "channel": "telegram",
    "contact_name": "Alice Smith",
    "created_at": "2026-03-11T10:00:00Z"
  }
}

conversation.updated​

Fires when thread metadata changes (assignment, folder, title, etc.).

{
  "event": "conversation.updated",
  "delivery_id": "12349",
  "data": {
    "thread_id": "telegram:123456789",
    "channel": "telegram",
    "changes": { "assigned_to": "agent@company.com" }
  }
}

conversation.closed​

Fires when a thread is marked as closed.

{
  "event": "conversation.closed",
  "delivery_id": "12350",
  "data": {
    "thread_id": "telegram:123456789",
    "channel": "telegram",
    "closed_at": "2026-03-11T11:00:00Z"
  }
}

handoff.requested​

Fires when the AI agent requests a human to take over.

{
  "event": "handoff.requested",
  "delivery_id": "12351",
  "data": {
    "thread_id": "telegram:123456789",
    "channel": "telegram",
    "reason": "Customer requested to speak with a human"
  }
}

draft.created​

Fires when the AI creates an auto-reply draft awaiting approval.

{
  "event": "draft.created",
  "delivery_id": "12352",
  "data": {
    "thread_id": "telegram:123456789",
    "channel": "telegram",
    "draft_text": "Thank you for your message! Our team will respond shortly.",
    "created_at": "2026-03-11T10:00:30Z"
  }
}

contact.updated​

Fires when a contact profile is updated.

{
  "event": "contact.updated",
  "delivery_id": "12353",
  "data": {
    "contact_id": "person_123",
    "changes": {
      "name": "Alice Smith",
      "email": "alice@example.com"
    }
  }
}