Event Reference

By Orqestra · Published September 25, 2026

Every event Orqestra can send, what triggers it, and what is in its data. The envelope around data is described in the overview. This is payload version 2026-09-01.

An event is sent only when something actually changed. Saving a record without changing it, or a provider re-sending the same notification, doesn't produce another event. Payloads are curated snapshots: provider-native fields, credentials, custom contact fields, AI prompts and model output are never included.

All events

Channel events

Sent for the channel instances the endpoint selects, with channel set.

message.received — A customer sent a message.
message.sent — An agent, Journey or AI Agent reply was accepted by the channel.
message.delivery_updated — An outbound message was delivered, read or failed.
message.deleted — An agent deleted a message. Content is not included.
message.ad_referral — A customer messaged from a Click-to-WhatsApp ad. Also sent as message.received.
chat.created — A new conversation thread opened on a channel.
chat.assigned — The assigned agent or team changed, including unassignment.
chat.status_changed — Open, pending, resolved or snoozed.
chat.escalated — A conversation was flagged for a human.
session.started — An agent, Journey or AI Agent session began.
session.ended — A session ended for any reason.
automation.started — A Journey or AI Agent run began.
automation.completed — A Journey or AI Agent run finished.
automation.failed — A Journey or AI Agent run stopped on an error.
broadcast.queued — A broadcast was queued to send now.
broadcast.scheduled — A broadcast was scheduled for later.
broadcast.completed — Every recipient was processed.
broadcast.cancelled — A broadcast was cancelled before finishing.
order.received — A customer placed a catalog order in chat.

Organization events

Not tied to a channel; channel is null.

contact.created — A new contact was added.
contact.updated — A contact’s name or identifiers changed.
contact.deleted — A contact was deleted. Only the ID is included.
contact.merged — Duplicate contacts were merged into one.
ticket.created — A ticket was opened.
ticket.updated — Status, priority, owner or links changed.
ticket.deleted — A ticket was deleted. Only IDs are included.
ticket.note_created — A note was added to a ticket.

Plus webhook.test, which you trigger yourself.

Messages

Messages on every channel — WhatsApp, Instagram, Web Chat, Telegram, TikTok Shop and Email — use the same events and the same message object.

`message.received`

A customer sent a message. Sent for each new inbound message. Messages imported as history are not sent.

Scope: channel. data: message.

{
  "data": {
    "message": {
      "caption": null,
      "chatId": "cmf2c5h8p0013cht7docs0004",
      "contactId": "cmf2c4t7n0011cnt7docs0003",
      "createdAt": "2026-09-24T02:15:07.000Z",
      "deletedAt": null,
      "direction": "INBOUND",
      "externalId": "wamid.HBgNNjI4MTIzNDU2Nzg5MBUCABIYFDNBQjE2QzY0MUE0NzJGOTg4QkQ5AA==",
      "id": "cmf2c7m3s0017msg7docs0009",
      "media": null,
      "referral": null,
      "replyToMessageId": null,
      "sessionId": "cmf2c6k1r0015ses7docs0005",
      "status": "RECEIVED",
      "subject": null,
      "text": "Halo, pesanan saya #1042 sudah dikirim belum?",
      "type": "text",
      "updatedAt": "2026-09-24T02:15:07.000Z"
    }
  }
}

`message.sent`

An agent, Journey or AI Agent reply was accepted by the channel. Sent once the channel accepts an outbound message, whoever wrote it — an agent, a Journey, an AI Agent or the API.

Scope: channel. data: message.

{
  "data": {
    "message": {
      "caption": null,
      "chatId": "cmf2c5h8p0013cht7docs0004",
      "contactId": "cmf2c4t7n0011cnt7docs0003",
      "createdAt": "2026-09-24T02:15:09.000Z",
      "deletedAt": null,
      "direction": "OUTBOUND",
      "externalId": "wamid.HBgNNjI4MTIzNDU2Nzg5MBUCABEYEjRGNkE4QzJBN0UxQjNEOTA1QwA=",
      "id": "cmf2c8p4u0019msg7docs0010",
      "media": null,
      "referral": null,
      "replyToMessageId": "cmf2c7m3s0017msg7docs0009",
      "sessionId": "cmf2c6k1r0015ses7docs0005",
      "status": "SENT",
      "subject": null,
      "text": "Sudah, kak. Resi JX0099881 — estimasi tiba besok.",
      "type": "text",
      "updatedAt": "2026-09-24T02:15:09.000Z"
    }
  }
}

`message.delivery_updated`

An outbound message was delivered, read or failed. Sent each time an outbound message’s status actually changes; a repeated receipt for the same status is not sent twice. Channels that report receipts: WhatsApp (SENT, DELIVERED, READ, FAILED) and Instagram (READ).

Scope: channel. data: message; changes — { "previous", "current" } for each changed field among status.

{
  "data": {
    "changes": {
      "status": {
        "current": "READ",
        "previous": "DELIVERED"
      }
    },
    "message": {
      "caption": null,
      "chatId": "cmf2c5h8p0013cht7docs0004",
      "contactId": "cmf2c4t7n0011cnt7docs0003",
      "createdAt": "2026-09-24T02:15:09.000Z",
      "deletedAt": null,
      "direction": "OUTBOUND",
      "externalId": "wamid.HBgNNjI4MTIzNDU2Nzg5MBUCABEYEjRGNkE4QzJBN0UxQjNEOTA1QwA=",
      "id": "cmf2c8p4u0019msg7docs0010",
      "media": null,
      "referral": null,
      "replyToMessageId": "cmf2c7m3s0017msg7docs0009",
      "sessionId": "cmf2c6k1r0015ses7docs0005",
      "status": "READ",
      "subject": null,
      "text": "Sudah, kak. Resi JX0099881 — estimasi tiba besok.",
      "type": "text",
      "updatedAt": "2026-09-24T02:41:30.000Z"
    }
  }
}

`message.deleted`

An agent deleted a message. Content is not included. Only IDs and the deletion time — the deleted content is not repeated.

Scope: channel. data: message — id, chatId, contactId, deletedAt.

{
  "data": {
    "message": {
      "chatId": "cmf2c5h8p0013cht7docs0004",
      "contactId": "cmf2c4t7n0011cnt7docs0003",
      "deletedAt": "2026-09-24T02:41:30.000Z",
      "id": "cmf2c8p4u0019msg7docs0010"
    }
  }
}

`message.ad_referral`

A customer messaged from a Click-to-WhatsApp ad. Also sent as message.received. Sent in addition to message.received for the same message, with referral always filled in. Subscribe to this one alone if you only want ad leads.

Scope: channel. data: message.

{
  "data": {
    "message": {
      "caption": null,
      "chatId": "cmf2c5h8p0013cht7docs0004",
      "contactId": "cmf2c4t7n0011cnt7docs0003",
      "createdAt": "2026-09-24T02:15:07.000Z",
      "deletedAt": null,
      "direction": "INBOUND",
      "externalId": "wamid.HBgNNjI4MTIzNDU2Nzg5MBUCABIYFDNBQjE2QzY0MUE0NzJGOTg4QkQ5AA==",
      "id": "cmf2c7m3s0017msg7docs0009",
      "media": null,
      "referral": {
        "body": "Chat kami untuk cek ongkir ke kotamu.",
        "ctwaClid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO",
        "headline": "Promo ongkir gratis",
        "imageUrl": "https://scontent.xx.fbcdn.net/v/t45.1600-4/example.jpg",
        "mediaType": "image",
        "receivedAt": "2026-09-24T02:15:07.000Z",
        "sourceId": "120210000000000001",
        "sourceType": "ad",
        "sourceUrl": "https://fb.me/3AbCdEfGh",
        "thumbnailUrl": null,
        "videoUrl": null,
        "welcomeMessage": "Halo! Ada yang bisa kami bantu?"
      },
      "replyToMessageId": null,
      "sessionId": "cmf2c6k1r0015ses7docs0005",
      "status": "RECEIVED",
      "subject": null,
      "text": "Halo, pesanan saya #1042 sudah dikirim belum?",
      "type": "text",
      "updatedAt": "2026-09-24T02:15:07.000Z"
    }
  }
}

Chats

Changes to a conversation thread. All carry the full chat as it is after the change.

`chat.created`

A new conversation thread opened on a channel. Sent when a contact’s first conversation on a channel instance is created.

Scope: channel. data: chat.

{
  "data": {
    "chat": {
      "assigneeId": null,
      "channelId": "cmf0q9b2d0003chn7docs0002",
      "contactId": "cmf2c4t7n0011cnt7docs0003",
      "createdAt": "2026-09-24T02:15:07.000Z",
      "id": "cmf2c5h8p0013cht7docs0004",
      "needsEscalation": false,
      "status": "OPEN",
      "teamId": null,
      "updatedAt": "2026-09-24T02:15:07.000Z"
    }
  }
}

`chat.assigned`

The assigned agent or team changed, including unassignment. changes lists only what changed — assigneeId, teamId or both. current: null means unassigned.

Scope: channel. data: chat; changes — { "previous", "current" } for each changed field among assigneeId, teamId.

{
  "data": {
    "changes": {
      "assigneeId": {
        "current": "cmf1u2s3r0007usr7docs0006",
        "previous": null
      },
      "teamId": {
        "current": "cmf1t4m5a0009tea7docs0007",
        "previous": null
      }
    },
    "chat": {
      "assigneeId": "cmf1u2s3r0007usr7docs0006",
      "channelId": "cmf0q9b2d0003chn7docs0002",
      "contactId": "cmf2c4t7n0011cnt7docs0003",
      "createdAt": "2026-09-24T02:15:07.000Z",
      "id": "cmf2c5h8p0013cht7docs0004",
      "needsEscalation": false,
      "status": "OPEN",
      "teamId": "cmf1t4m5a0009tea7docs0007",
      "updatedAt": "2026-09-24T02:41:30.000Z"
    }
  }
}

`chat.status_changed`

Open, pending, resolved or snoozed. Status values: OPEN, PENDING, RESOLVED, SNOOZED.

Scope: channel. data: chat; changes — { "previous", "current" } for each changed field among status.

{
  "data": {
    "changes": {
      "status": {
        "current": "RESOLVED",
        "previous": "OPEN"
      }
    },
    "chat": {
      "assigneeId": "cmf1u2s3r0007usr7docs0006",
      "channelId": "cmf0q9b2d0003chn7docs0002",
      "contactId": "cmf2c4t7n0011cnt7docs0003",
      "createdAt": "2026-09-24T02:15:07.000Z",
      "id": "cmf2c5h8p0013cht7docs0004",
      "needsEscalation": false,
      "status": "RESOLVED",
      "teamId": "cmf1t4m5a0009tea7docs0007",
      "updatedAt": "2026-09-24T02:41:30.000Z"
    }
  }
}

`chat.escalated`

A conversation was flagged for a human. Sent when needsEscalation turns true — an AI Agent or Journey handed over, or the customer asked for a person.

Scope: channel. data: chat.

{
  "data": {
    "chat": {
      "assigneeId": null,
      "channelId": "cmf0q9b2d0003chn7docs0002",
      "contactId": "cmf2c4t7n0011cnt7docs0003",
      "createdAt": "2026-09-24T02:15:07.000Z",
      "id": "cmf2c5h8p0013cht7docs0004",
      "needsEscalation": true,
      "status": "OPEN",
      "teamId": null,
      "updatedAt": "2026-09-24T02:41:30.000Z"
    }
  }
}

Sessions

A session records who or what is handling a conversation. Every agent, Journey and AI Agent session produces a start and an end.

`session.started`

An agent, Journey or AI Agent session began.

Scope: channel. data: session.

{
  "data": {
    "session": {
      "agentId": null,
      "chatId": "cmf2c5h8p0013cht7docs0004",
      "endReason": null,
      "endedAt": null,
      "id": "cmf2c6k1r0015ses7docs0005",
      "sessionType": "ai_bot_v2",
      "startedAt": "2026-09-24T02:15:07.000Z"
    }
  }
}

`session.ended`

A session ended for any reason. Carries endedAt and endReason.

Scope: channel. data: session.

{
  "data": {
    "session": {
      "agentId": null,
      "chatId": "cmf2c5h8p0013cht7docs0004",
      "endReason": "ESCALATED",
      "endedAt": "2026-09-24T02:41:30.000Z",
      "id": "cmf2c6k1r0015ses7docs0005",
      "sessionType": "ai_bot_v2",
      "startedAt": "2026-09-24T02:15:07.000Z"
    }
  }
}

Automation

One event per Journey or AI Agent run, alongside the session events. Every run belongs to a conversation, so these arrive as channel events — tick them under Channel events.

`automation.started`

A Journey or AI Agent run began.

Scope: channel or organization. data: automation; automationRun.

{
  "data": {
    "automation": {
      "id": "cmf0p1l2n0005pip7docs0012",
      "name": "Order status assistant",
      "type": "AI_AGENT"
    },
    "automationRun": {
      "chatId": "cmf2c5h8p0013cht7docs0004",
      "completedAt": null,
      "contactId": null,
      "errorCode": null,
      "id": "cmf2c6k1r0015ses7docs0005",
      "startedAt": "2026-09-24T02:15:07.000Z",
      "status": "STARTED"
    }
  }
}

`automation.completed`

A Journey or AI Agent run finished.

Scope: channel or organization. data: automation; automationRun.

{
  "data": {
    "automation": {
      "id": "cmf0p1l2n0005pip7docs0012",
      "name": "Order status assistant",
      "type": "AI_AGENT"
    },
    "automationRun": {
      "chatId": "cmf2c5h8p0013cht7docs0004",
      "completedAt": "2026-09-24T02:41:30.000Z",
      "contactId": null,
      "errorCode": null,
      "id": "cmf2c6k1r0015ses7docs0005",
      "startedAt": "2026-09-24T02:15:07.000Z",
      "status": "COMPLETED"
    }
  }
}

`automation.failed`

A Journey or AI Agent run stopped on an error. automationRun.errorCode says why. Error messages and prompts are never included.

Scope: channel or organization. data: automation; automationRun.

{
  "data": {
    "automation": {
      "id": "cmf0p1l2n0005pip7docs0012",
      "name": "Order status assistant",
      "type": "AI_AGENT"
    },
    "automationRun": {
      "chatId": "cmf2c5h8p0013cht7docs0004",
      "completedAt": "2026-09-24T02:41:30.000Z",
      "contactId": null,
      "errorCode": "LLM_TIMEOUT",
      "id": "cmf2c6k1r0015ses7docs0005",
      "startedAt": "2026-09-24T02:15:07.000Z",
      "status": "FAILED"
    }
  }
}

Broadcasts

The lifecycle of a broadcast. Individual recipient messages are not sent as events.

`broadcast.queued`

A broadcast was queued to send now.

Scope: channel. data: broadcast.

{
  "data": {
    "broadcast": {
      "channelId": "cmf0q9b2d0003chn7docs0002",
      "createdAt": "2026-09-24T02:15:07.000Z",
      "failureCount": 0,
      "id": "cmf4b1r2c0031bct7docs0011",
      "name": "Flash sale 25.9",
      "sendAt": null,
      "status": "QUEUED",
      "successCount": 0,
      "totalRecipients": 1250,
      "updatedAt": "2026-09-24T02:15:07.000Z"
    }
  }
}

`broadcast.scheduled`

A broadcast was scheduled for later.

Scope: channel. data: broadcast.

{
  "data": {
    "broadcast": {
      "channelId": "cmf0q9b2d0003chn7docs0002",
      "createdAt": "2026-09-24T02:15:07.000Z",
      "failureCount": 0,
      "id": "cmf4b1r2c0031bct7docs0011",
      "name": "Flash sale 25.9",
      "sendAt": "2026-09-25T01:00:00.000Z",
      "status": "SCHEDULED",
      "successCount": 0,
      "totalRecipients": 1250,
      "updatedAt": "2026-09-24T02:15:07.000Z"
    }
  }
}

`broadcast.completed`

Every recipient was processed. Final counts are in successCount and failureCount.

Scope: channel. data: broadcast.

{
  "data": {
    "broadcast": {
      "channelId": "cmf0q9b2d0003chn7docs0002",
      "createdAt": "2026-09-24T02:15:07.000Z",
      "failureCount": 12,
      "id": "cmf4b1r2c0031bct7docs0011",
      "name": "Flash sale 25.9",
      "sendAt": null,
      "status": "COMPLETED",
      "successCount": 1238,
      "totalRecipients": 1250,
      "updatedAt": "2026-09-24T02:41:30.000Z"
    }
  }
}

`broadcast.cancelled`

A broadcast was cancelled before finishing.

Scope: channel. data: broadcast.

{
  "data": {
    "broadcast": {
      "channelId": "cmf0q9b2d0003chn7docs0002",
      "createdAt": "2026-09-24T02:15:07.000Z",
      "failureCount": 0,
      "id": "cmf4b1r2c0031bct7docs0011",
      "name": "Flash sale 25.9",
      "sendAt": null,
      "status": "CANCELLED",
      "successCount": 0,
      "totalRecipients": 1250,
      "updatedAt": "2026-09-24T02:41:30.000Z"
    }
  }
}

Orders

Catalog orders placed inside a chat.

`order.received`

A customer placed a catalog order in chat.

Scope: channel. data: order.

{
  "data": {
    "order": {
      "chatId": "cmf2c5h8p0013cht7docs0004",
      "contactId": "cmf2c4t7n0011cnt7docs0003",
      "createdAt": "2026-09-24T02:15:07.000Z",
      "currency": "IDR",
      "id": "cmf5o2r3d0035ord7docs0015",
      "itemCount": 2,
      "status": "PENDING",
      "total": "349000"
    }
  }
}

Contacts

Organization events. They arrive with channel: null and ignore the endpoint’s channel selection.

`contact.created`

A new contact was added.

Scope: organization. data: contact.

{
  "data": {
    "contact": {
      "createdAt": "2026-09-24T02:15:07.000Z",
      "displayName": "Budi Santoso",
      "id": "cmf2c4t7n0011cnt7docs0003",
      "identifiers": [
        {
          "type": "WHATSAPP",
          "value": "6281234567890"
        }
      ],
      "updatedAt": "2026-09-24T02:15:07.000Z"
    }
  }
}

`contact.updated`

A contact’s name or identifiers changed. Sent when the display name or identifiers change. changes lists only what changed.

Scope: organization. data: contact; changes — { "previous", "current" } for each changed field among displayName, identifiers.

{
  "data": {
    "changes": {
      "displayName": {
        "current": "Budi S. (Jakarta)",
        "previous": "Budi Santoso"
      }
    },
    "contact": {
      "createdAt": "2026-09-24T02:15:07.000Z",
      "displayName": "Budi S. (Jakarta)",
      "id": "cmf2c4t7n0011cnt7docs0003",
      "identifiers": [
        {
          "type": "WHATSAPP",
          "value": "6281234567890"
        }
      ],
      "updatedAt": "2026-09-24T02:41:30.000Z"
    }
  }
}

`contact.deleted`

A contact was deleted. Only the ID is included. A tombstone: the ID and the deletion time.

Scope: organization. data: contact — id, deletedAt.

{
  "data": {
    "contact": {
      "deletedAt": "2026-09-24T02:41:30.000Z",
      "id": "cmf2c4t7n0011cnt7docs0003"
    }
  }
}

`contact.merged`

Duplicate contacts were merged into one. sourceContactIds were merged into contact and no longer exist. Repoint anything you stored under those IDs.

Scope: organization. data: sourceContactIds — array of contact IDs; contact.

{
  "data": {
    "contact": {
      "createdAt": "2026-09-24T02:15:07.000Z",
      "displayName": "Budi Santoso",
      "id": "cmf2c4t7n0011cnt7docs0003",
      "identifiers": [
        {
          "type": "WHATSAPP",
          "value": "6281234567890"
        },
        {
          "type": "INSTAGRAM",
          "value": "17841400000000001"
        }
      ],
      "updatedAt": "2026-09-24T02:41:30.000Z"
    },
    "sourceContactIds": [
      "cmf2c9q5v0023cnt7docs0013"
    ]
  }
}

Tickets

Organization events. They arrive with channel: null and ignore the endpoint’s channel selection.

`ticket.created`

A ticket was opened.

Scope: organization. data: ticket.

{
  "data": {
    "ticket": {
      "assigneeId": "cmf1u2s3r0007usr7docs0006",
      "chatId": "cmf2c5h8p0013cht7docs0004",
      "contactId": "cmf2c4t7n0011cnt7docs0003",
      "createdAt": "2026-09-24T02:41:30.000Z",
      "id": "cmf3t6k9t0021tkt7docs0008",
      "priority": "HIGH",
      "resolvedAt": null,
      "status": "OPEN",
      "teamId": "cmf1t4m5a0009tea7docs0007",
      "ticketNumber": 1042,
      "title": "Paket #1042 belum sampai",
      "updatedAt": "2026-09-24T02:41:30.000Z"
    }
  }
}

`ticket.updated`

Status, priority, owner or links changed. Sent when the title, status, priority, assignee, team, linked contact or chat, or resolution time changes. changes lists only what changed.

Scope: organization. data: ticket; changes — { "previous", "current" } for each changed field among title, status, priority, assigneeId, teamId, contactId, chatId, resolvedAt.

{
  "data": {
    "changes": {
      "resolvedAt": {
        "current": "2026-09-24T02:41:30.000Z",
        "previous": null
      },
      "status": {
        "current": "RESOLVED",
        "previous": "OPEN"
      }
    },
    "ticket": {
      "assigneeId": "cmf1u2s3r0007usr7docs0006",
      "chatId": "cmf2c5h8p0013cht7docs0004",
      "contactId": "cmf2c4t7n0011cnt7docs0003",
      "createdAt": "2026-09-24T02:41:30.000Z",
      "id": "cmf3t6k9t0021tkt7docs0008",
      "priority": "HIGH",
      "resolvedAt": "2026-09-24T02:41:30.000Z",
      "status": "RESOLVED",
      "teamId": "cmf1t4m5a0009tea7docs0007",
      "ticketNumber": 1042,
      "title": "Paket #1042 belum sampai",
      "updatedAt": "2026-09-24T02:41:30.000Z"
    }
  }
}

`ticket.deleted`

A ticket was deleted. Only IDs are included. A tombstone: IDs and the deletion time.

Scope: organization. data: ticket — id, ticketNumber, contactId, chatId, deletedAt.

{
  "data": {
    "ticket": {
      "chatId": "cmf2c5h8p0013cht7docs0004",
      "contactId": "cmf2c4t7n0011cnt7docs0003",
      "deletedAt": "2026-09-24T02:41:30.000Z",
      "id": "cmf3t6k9t0021tkt7docs0008",
      "ticketNumber": 1042
    }
  }
}

`ticket.note_created`

A note was added to a ticket.

Scope: organization. data: ticketNote.

{
  "data": {
    "ticketNote": {
      "authorId": "cmf1u2s3r0007usr7docs0006",
      "body": "Kurir konfirmasi paket tertahan di hub Cakung.",
      "createdAt": "2026-09-24T02:41:30.000Z",
      "id": "cmf3n7t1e0025nte7docs0014",
      "ticketId": "cmf3t6k9t0021tkt7docs0008"
    }
  }
}

`webhook.test`

Sent only when you click Send test. It doesn't describe a real change, and you can't subscribe to it. It uses the same headers, signature and envelope as every other event. Its channel is the first channel the endpoint selects, or null if none. Answer it 2xx like any other event. Don't act on it.

{
  "data": {
    "test": true
  }
}

Objects

The resources inside data. A field whose type ends in | null is sent as null when there is no value. Timestamps are UTC, in ISO 8601 format.

`message`

One message in a conversation, inbound or outbound, on any channel.

id string
Orqestra message ID.
externalId string | null
The channel’s own ID for this message — the WhatsApp wamid, Instagram mid, and so on. Use it to correlate with provider logs.
chatId string
The conversation this message belongs to.
contactId string
The customer.
sessionId string | null
The agent, Journey or AI Agent session that was active when the message was stored.
replyToMessageId string | null
The Orqestra message this one quotes or replies to.
direction string
INBOUND (from the customer) or OUTBOUND (from you).
type string
Content type as the channel reports it, e.g. text, image, document, interactive.
text string | null
Message text.
caption string | null
Caption on a media message.
subject string | null
Email subject. Email channel only.
status string
Latest delivery state: RECEIVED for inbound; SENT, DELIVERED, READ or FAILED for outbound.
media object | null
Attachment metadata — id, mimeType, sizeBytes, fileName. The file itself is not included; fetch it through the API.
referral object | null
The Click-to-WhatsApp ad the customer came from, or null. See referral.
createdAt timestamp
When the message was stored.
updatedAt timestamp
Last change, such as a delivery status update.
deletedAt timestamp | null
When an agent deleted it.

`message.referral`

Present on the first message a customer sends from a Click-to-WhatsApp ad. Meta’s raw referral object is never forwarded — only these fields.

sourceType string | null
ad or post.
sourceId string | null
Meta ad or post ID.
sourceUrl string | null
Link to the ad or post.
headline string | null
Ad headline.
body string | null
Ad body text.
mediaType string | null
image or video.
imageUrl string | null
Ad image URL (hosted by Meta; may expire).
videoUrl string | null
Ad video URL (hosted by Meta; may expire).
thumbnailUrl string | null
Video thumbnail URL.
ctwaClid string | null
Click ID for the Conversions API. Absent for ads shown in WhatsApp Status — test for referral, not for this field, to decide whether a lead came from an ad.
welcomeMessage string | null
The ad’s pre-filled welcome message.
receivedAt timestamp
When the referral arrived.

`chat`

A conversation thread with one contact on one channel instance.

id string
Chat ID.
contactId string
The customer.
channelId string
The channel instance (a specific WhatsApp number, Instagram account, …).
status string
OPEN, PENDING, RESOLVED or SNOOZED.
assigneeId string | null
Assigned agent (user ID), or null.
teamId string | null
Owning team, or null.
needsEscalation boolean
true while the chat is waiting for a human.
createdAt timestamp
When the chat was created.
updatedAt timestamp
When the chat last changed.

`contact`

A customer. Custom contact fields are not included in this API version — read them through the API.

id string
Contact ID.
displayName string | null
The name your team set, or else the profile name from the channel.
identifiers array
How the contact is reached, as { "type", "value" } pairs. type is one of WHATSAPP, INSTAGRAM, WEBCHAT, TELEGRAM, TIKTOK, EMAIL; value is the phone number, account ID or email address.
createdAt timestamp
When the contact was created.
updatedAt timestamp
When the contact last changed.

`ticket`

A ticket: an issue tracked beyond a single conversation.

id string
Ticket ID.
ticketNumber number
The human-readable ticket number shown in the dashboard.
title string
Ticket title.
status string
OPEN, IN_PROGRESS, RESOLVED or CLOSED.
priority string
LOW, MEDIUM, HIGH or URGENT.
contactId string | null
Linked contact.
chatId string | null
Linked conversation.
assigneeId string | null
Assigned agent.
teamId string | null
Owning team.
resolvedAt timestamp | null
When the ticket was resolved.
createdAt timestamp
When the ticket was created.
updatedAt timestamp
When the ticket last changed.

`ticketNote`

An internal note on a ticket. Notes are never shown to the customer.

id string
Note ID.
ticketId string
The ticket.
authorId string | null
The user who wrote it.
body string
Note text.
createdAt timestamp
When the note was added.

`session`

Who or what is handling a conversation: a human agent, a Journey or an AI Agent. A chat has many sessions over its life.

id string
Session ID.
chatId string
The conversation.
sessionType string
agent (human), flow (Journey), ai_bot_v2 (AI Agent) or coexistence (replies sent from the WhatsApp Business app).
agentId string | null
The agent, for agent sessions.
startedAt timestamp
When the session started.
endedAt timestamp | null
When it ended; null while active.
endReason string | null
Why it ended, e.g. MANUAL, TIMEOUT, REASSIGNED, ESCALATED, FLOW_COMPLETE.

`broadcast`

A template message sent to many contacts.

id string
Broadcast ID.
channelId string
The channel instance it sends from.
name string
Broadcast name.
status string
SCHEDULED, QUEUED, PROCESSING, COMPLETED, PARTIAL, FAILED or CANCELLED.
totalRecipients number
Recipients targeted.
successCount number
Sent successfully so far.
failureCount number
Failed so far.
sendAt timestamp | null
Scheduled send time, for scheduled broadcasts.
createdAt timestamp
When the broadcast was created.
updatedAt timestamp
When it last changed.

`order`

An order a customer placed from your catalog inside a chat.

id string
Order ID.
chatId string
The conversation it was placed in.
contactId string
The customer.
currency string
ISO 4217 currency code, e.g. IDR.
total string
Order total as a decimal string, to avoid floating-point rounding.
itemCount number
Total quantity across line items.
status string
Orqestra’s processing state for the order, e.g. PENDING.
createdAt timestamp
When the order arrived.

`automation`

The Journey or AI Agent that ran.

id string
Journey or AI Agent ID.
type string
JOURNEY or AI_AGENT.
name string
Its name in the builder.

`automationRun`

One execution of that automation. Prompts, model output and runtime variables are never included.

id string
Run ID — the same value as the session.id it runs in.
chatId string | null
The conversation.
contactId string | null
The customer, when known. Currently null; use chatId.
status string
STARTED, COMPLETED or FAILED.
startedAt timestamp
When the run started.
completedAt timestamp | null
When it finished.
errorCode string | null
A short machine-readable reason on automation.failed.

Versioning

Each endpoint is pinned to a payload version, shown in every event as apiVersion. Within a version, Orqestra only adds: new fields, new event types (which you must opt into), and new values for fields that list examples. Removing, renaming or retyping a field, or changing what one means, only happens under a new version date.

All events

Channel events

Organization events

Messages

message.received

message.sent

message.delivery_updated

message.deleted

message.ad_referral

Chats

chat.created

chat.assigned

chat.status_changed

chat.escalated

Sessions

session.started

session.ended

Automation

automation.started

automation.completed

automation.failed

Broadcasts

broadcast.queued

broadcast.scheduled

broadcast.completed

broadcast.cancelled

Orders

order.received

Contacts

contact.created

contact.updated

contact.deleted

contact.merged

Tickets

ticket.created

ticket.updated

ticket.deleted

ticket.note_created

webhook.test

Objects

message

message.referral

chat

contact

ticket

ticketNote

session

broadcast

order

automation

automationRun

Versioning

Overview & quick start

Verifying Signatures

Delivery & Retries

`message.received`

`message.sent`

`message.delivery_updated`

`message.deleted`

`message.ad_referral`

`chat.created`

`chat.assigned`

`chat.status_changed`

`chat.escalated`

`session.started`

`session.ended`

`automation.started`

`automation.completed`

`automation.failed`

`broadcast.queued`

`broadcast.scheduled`

`broadcast.completed`

`broadcast.cancelled`

`order.received`

`contact.created`

`contact.updated`

`contact.deleted`

`contact.merged`

`ticket.created`

`ticket.updated`

`ticket.deleted`

`ticket.note_created`

`webhook.test`

`message`

`message.referral`

`chat`

`contact`

`ticket`

`ticketNote`

`session`

`broadcast`

`order`

`automation`

`automationRun`