Skip to main content

Events

Every delivery is a POST with this body; data depends on the event:

{
  "event": "<event>",
  "delivery_id": "<id>",
  "data": {}
}

Event names and their meaning come from the API itself; the data examples are maintained by hand.

message.received​

A new inbound message was stored on a conversation.

{
  "event": "message.received",
  "delivery_id": "18273",
  "data": {
    "channel": "telegram",
    "account_id": "7531",
    "thread_id": "telegram:987654321",
    "message": {
      "message_id": "telegram:m_5a9b1c2d",
      "channel": "telegram",
      "peer": "987654321",
      "text": "Hi, I have a question about your services",
      "html": null,
      "is_outgoing": false,
      "sent_at": "2026-08-22T14:30:45Z",
      "media_type": "text",
      "from_id": "user_5a9b",
      "from_name": "Alice Johnson",
      "attachments": null,
      "reply_to_message_id": null,
      "db_id": "5042",
      "metadata": null,
      "action": null
    },
    "thread": {
      "thread_id": "telegram:987654321",
      "channel": "telegram",
      "last_message_preview": "Hi, I have a question...",
      "last_message_ts": "2026-08-22T14:30:45Z",
      "unread_count": 1,
      "title": "Alice Johnson",
      "account_id": "7531",
      "meta": null
    },
    "source": "telegram_sync",
    "timestamp": "2026-08-22T14:30:46Z"
  }
}

message.updated​

A message was edited on its channel.

{
  "event": "message.updated",
  "delivery_id": "18273",
  "data": {
    "channel": "telegram",
    "account_id": "7531",
    "thread_id": "telegram:987654321",
    "message": {
      "message_id": "telegram:m_5a9b1c2d",
      "channel": "telegram",
      "peer": "987654321",
      "text": "Hi, I have a question about your services (edited)",
      "html": null,
      "is_outgoing": true,
      "sent_at": "2026-08-22T14:30:45Z",
      "media_type": "text",
      "from_id": "user_5a9b",
      "from_name": "Acme Support",
      "attachments": null,
      "reply_to_message_id": null,
      "db_id": "5043",
      "metadata": null,
      "action": null
    },
    "thread": {
      "thread_id": "telegram:987654321",
      "channel": "telegram",
      "last_message_preview": "Hi, I have a question about...",
      "last_message_ts": "2026-08-22T14:31:15Z",
      "unread_count": 0,
      "title": "Alice Johnson",
      "account_id": "7531",
      "meta": null
    },
    "source": "messages.update",
    "timestamp": "2026-08-22T14:31:15Z"
  }
}

message.deleted​

A message was deleted on its channel.

{
  "event": "message.deleted",
  "delivery_id": "18273",
  "data": {
    "channel": "telegram",
    "account_id": "7531",
    "thread_id": "telegram:987654321",
    "message": {
      "message_id": "telegram:m_5a9b1c2d",
      "channel": "telegram",
      "peer": "987654321",
      "text": "",
      "html": null,
      "is_outgoing": true,
      "sent_at": "2026-08-22T14:30:45Z",
      "media_type": "text",
      "from_id": "user_5a9b",
      "from_name": "Acme Support",
      "attachments": null,
      "reply_to_message_id": null,
      "db_id": "5043",
      "metadata": null,
      "action": null
    },
    "thread": {
      "thread_id": "telegram:987654321",
      "channel": "telegram",
      "last_message_preview": "Hi, I have a question about...",
      "last_message_ts": "2026-08-22T14:30:45Z",
      "unread_count": 0,
      "title": "Alice Johnson",
      "account_id": "7531",
      "meta": null
    },
    "source": "messages.delete",
    "timestamp": "2026-08-22T14:32:00Z"
  }
}

conversation.started​

A person wrote in a conversation for the first time.

{
  "event": "conversation.started",
  "delivery_id": "18273",
  "data": {
    "thread_id": 1042,
    "workspace_id": 167,
    "channel": "telegram",
    "account_id": "7531",
    "thread_ref": "telegram:15550100",
    "title": "Alice Example",
    "first_message": {
      "message_id": "m_88214",
      "text": "Hi, I have a question about your services",
      "from_name": "Alice Example",
      "sent_at": "2026-08-22T14:25:00Z"
    }
  }
}

conversation.updated​

Conversation metadata changed: title, status, assignee or tags.

{
  "event": "conversation.updated",
  "delivery_id": "18273",
  "data": {
    "channel": "telegram",
    "account_id": "7531",
    "thread_id": "telegram:987654321",
    "thread": {
      "thread_id": "telegram:987654321",
      "channel": "telegram",
      "last_message_preview": "Thank you for reaching out",
      "last_message_ts": "2026-08-22T14:30:45Z",
      "unread_count": 0,
      "title": "Alice Johnson - Resolved",
      "account_id": "7531",
      "meta": {
        "assignee_id": 42,
        "tags": [
          "support",
          "urgent"
        ],
        "status": "in_progress"
      }
    },
    "source": "thread.update",
    "timestamp": "2026-08-22T14:30:45Z"
  }
}

handoff.requested​

A human is needed on this conversation; data.origin says who asked.

{
  "event": "handoff.requested",
  "delivery_id": "18273",
  "data": {
    "thread_id": 1042,
    "workspace_id": 167,
    "reason": "Customer asked for a human",
    "origin": "api",
    "agent_id": null,
    "job_id": null
  }
}

draft.created​

An agent produced a reply that awaits approval before sending.

{
  "event": "draft.created",
  "delivery_id": "18273",
  "data": {
    "draft_id": 2104,
    "thread_id": "telegram:987654321",
    "channel_account_id": "7531",
    "channel_ref": null,
    "thread_title": "Alice Johnson",
    "trigger_sender": "Alice Johnson",
    "trigger_text": "What are your opening hours?",
    "response_text": "Our business is open Monday to Friday, 9 AM to 6 PM. Is there anything else I can help you with?",
    "created_at": "2026-08-22T14:35:15Z",
    "expires_at": "2026-08-22T14:40:15Z",
    "channel_type": "telegram",
    "auto_send": false,
    "draft_type": "auto_reply",
    "attachment_file_ids": null,
    "agent_name": "Support Assistant",
    "agent_id": 77,
    "trace_id": "tr_5f1a2b3c",
    "prompt_source": "global",
    "model_used": "claude-3-5-sonnet-20241022"
  }
}

fields confirmed from apps/api-gateway/src/services/auto_reply_event_service.py::DraftCreatedPayload

contact.updated​

A contact's profile fields changed.

{
  "event": "contact.updated",
  "delivery_id": "18273",
  "data": {
    "person_id": 5042,
    "display_name": "Alice Johnson",
    "first_name": "Alice",
    "last_name": "Johnson",
    "email": "alice@example.com",
    "phone": "+1 555 0100",
    "notes": "VIP customer, prefers email communication",
    "staff_role": null,
    "capabilities": [
      "voice",
      "email"
    ],
    "preferred_channel_account_id": 7531,
    "updated_at": "2026-08-22T14:35:00Z",
    "changed_fields": [
      "email",
      "notes"
    ]
  }
}

fields inferred from person table schema; no active publisher found in code

session.completed​

An agent run finished; data carries kind, session_id, trace_id, agent_id and the outcome.

{
  "event": "session.completed",
  "delivery_id": "18273",
  "data": {
    "kind": "agent",
    "session_id": "sess_a1b2c3d4",
    "trace_id": "tr_5f1a2b3c",
    "agent_id": 77,
    "workspace_id": 1,
    "thread_id": 5042,
    "channel": "telegram",
    "source": "telegram_sync",
    "started_at": "2026-08-22T14:25:00Z",
    "ended_at": "2026-08-22T14:30:45Z",
    "duration_seconds": 345,
    "model": "claude-3-5-sonnet-20241022",
    "tokens": {
      "input": 1024,
      "output": 256
    },
    "tools_used": [
      "get_contact_info",
      "create_ticket"
    ],
    "outcome": "success",
    "metadata": {}
  }
}

call.started​

A voice call connected; data carries call_id, agent_id and target.

{
  "event": "call.started",
  "delivery_id": "18273",
  "data": {
    "call_id": "c_5f1a2b3c",
    "channel": "telegram",
    "target": "+1 555 0100",
    "agent_id": 77,
    "direction": "inbound",
    "metadata": {
      "customer_metadata": {
        "order_id": "ORD-12345"
      }
    }
  }
}

call.ended​

A voice call ended; data carries duration, status and outcome.

{
  "event": "call.ended",
  "delivery_id": "18273",
  "data": {
    "call_id": "c_5f1a2b3c",
    "workspace_id": 1,
    "channel": "telegram",
    "thread_id": 5042,
    "channel_ref": "telegram:987654321",
    "agent_id": 77,
    "started_at": "2026-08-22T14:25:00Z",
    "ended_at": "2026-08-22T14:30:45Z",
    "duration_seconds": 345,
    "outcome": "success",
    "end_reason": "user_hangup",
    "metadata": {}
  }
}

transcript.turn​

One transcript turn of a live call, ordered by data.turn_number.

{
  "event": "transcript.turn",
  "delivery_id": "18273",
  "data": {
    "call_id": "c_5f1a2b3c",
    "turn_number": 1,
    "role": "user",
    "text": "Hi, I need help with my account",
    "ts": "2026-08-22T14:25:15Z",
    "agent_id": 77,
    "metadata": {}
  }
}

transcript.ready​

Terminal event for a call: the full transcript is stored.

{
  "event": "transcript.ready",
  "delivery_id": "18273",
  "data": {
    "call_id": "c_5f1a2b3c",
    "turns": [
      {
        "turn_number": 1,
        "role": "user",
        "text": "Hi, I need help with my account",
        "ts": "2026-08-22T14:25:15Z"
      },
      {
        "turn_number": 2,
        "role": "agent",
        "text": "Of course! I'd be happy to help. Can you provide your account number?",
        "ts": "2026-08-22T14:25:18Z"
      },
      {
        "turn_number": 3,
        "role": "user",
        "text": "Sure, it's ACC-98765",
        "ts": "2026-08-22T14:25:22Z"
      }
    ],
    "agent_id": 77,
    "metadata": {}
  }
}

partner.signup.ready​

A partner-referred sale finished provisioning; data carries order_ref, venue_name, widget_key, invited_email and the Stripe session id.

{
  "event": "partner.signup.ready",
  "delivery_id": "18273",
  "data": {
    "partner": "ua-pro",
    "order_ref": "UAP-2026-00417",
    "session_id": "cs_live_a1B2c3D4e5F6g7H8i9J0",
    "venue_name": "Central Cafe",
    "widget_key": "76840d21-e196-49e1-b163-50d88fe6705c",
    "invited_email": "owner@central-cafe.example"
  }
}

partner.payment.succeeded​

Money landed on a partner-referred sale — the first charge or any renewal; data carries order_ref, amount_cents, currency, kind and paid_at.

{
  "event": "partner.payment.succeeded",
  "delivery_id": "18273",
  "data": {
    "partner": "ua-pro",
    "order_ref": "UAP-2026-00417",
    "session_id": "cs_live_a1B2c3D4e5F6g7H8i9J0",
    "venue_name": "Central Cafe",
    "amount_cents": 3900,
    "currency": "eur",
    "kind": "renewal",
    "paid_at": "2026-09-27T08:14:03Z",
    "invoice_id": "in_1U8uBVCVrRnGYtgqQ48ucl1Y"
  }
}