Webhooks

Set up webhooks to receive notifications when conversations, participants, or communications change in Conversation Orchestrator. Each notification includes the event type, a timestamp, and the affected resource.

To receive webhooks, add one or more status callback URLs to your conversation configuration.

Configure status callbacks

Add status callback URLs when you create or update a configuration using the Twilio Console or the Conversation Orchestrator API reference.

To configure status callbacks in the Console, follow these steps:

Sign in to the Twilio Console.
Go to Products & services > Conversation Orchestrator > Conversation configurations.
Select your conversation configuration.
In the Details section, click Edit.
In the Webhook section of the Edit details modal, enter your webhook URL in the Callback URL field and select an HTTP method.
Click Save changes.

To configure status callbacks with the API, include the statusCallbacks array when you create or update a Configuration resource. Status callback URLs must use HTTPS with a public host.

Event types

Conversation Orchestrator sends the following event types:

Event type	Description
`CONVERSATION_CREATED`	A new conversation starts.
`CONVERSATION_UPDATED`	A conversation's status or name changes.
`PARTICIPANT_ADDED`	A participant joins a conversation.
`PARTICIPANT_UPDATED`	A participant's details change.
`PARTICIPANT_REMOVED`	A participant leaves a conversation.
`COMMUNICATION_CREATED`	A new message or transcription joins a conversation.
`COMMUNICATION_UPDATED`	A communication's details change.

Webhook payload structure

Every webhook payload is a JSON object with three top-level properties:

Property	Type	Description
`eventType`	string	The event that triggered the webhook. See Event types for possible values.
`timestamp`	string	The date and time when the event occurred, in ISO 8601 format (UTC).
`data`	object	The resource object. The structure depends on the event type.

The structure of the data object depends on the event type:

For CONVERSATION_CREATED and CONVERSATION_UPDATED events, data contains a Conversation resource.
For PARTICIPANT_ADDED, PARTICIPANT_UPDATED, and PARTICIPANT_REMOVED events, data contains a Participant resource.
For COMMUNICATION_CREATED and COMMUNICATION_UPDATED events, data contains a Communication resource.

Conversation resource

The data object for conversation events contains the following properties:

Property	Type	Description
`id`	string	The conversation ID.
`accountId`	string	The account SID.
`configurationId`	string	The conversation configuration ID.
`configuration`	object	The conversation configuration, including channel settings, capture rules, and status callbacks.
`status`	string	The conversation status. Possible values: `ACTIVE`, `INACTIVE`, `CLOSED`.
`name`	string	The conversation name.
`createdAt`	string	The date and time when the conversation was created, in ISO 8601 format.
`updatedAt`	string	The date and time when the conversation was last updated, in ISO 8601 format.

Participant resource

The data object for participant events contains the following properties:

Property	Type	Description
`id`	string	The participant ID.
`conversationId`	string	The conversation ID.
`accountId`	string	The account SID.
`name`	string	The participant display name.
`type`	string	The participant type. Possible values: `CUSTOMER`, `HUMAN_AGENT`, `AI_AGENT`, `AGENT`, or `UNKNOWN`.
`profileId`	string or null	The profile ID associated with Conversation Memory. It's resolved for `CUSTOMER` participants only.
`addresses`	array of objects	The participant's communication addresses. Each object contains `address`, `channel`, and `channelId`.
`createdAt`	string or null	The date and time when the participant was added, in ISO 8601 format.
`updatedAt`	string or null	The date and time when the participant was last updated, in ISO 8601 format.

Communication resource

The data object for communication events contains the following properties:

Property	Type	Description
`id`	string	The communication ID.
`conversationId`	string	The conversation ID.
`accountId`	string	The account SID.
`author`	object	The sender's address. Contains `address`, `channel`, and `participantId`.
`content`	object	The communication content, which includes a `type` field (`TEXT` or `TRANSCRIPTION`), the message `text`, and, for voice transcriptions, a `transcription` object with word-level timing data.
`channelId`	string	The channel-specific reference ID (for example, a Message SID or Call SID).
`recipients`	array of objects	The recipients of the communication. Each object contains `address`, `channel`, `participantId`, and `deliveryStatus`.
`occurredAt`	string	The date and time when the communication occurred, in ISO 8601 format.
`createdAt`	string	The date and time when the communication was created, in ISO 8601 format.
`updatedAt`	string	The date and time when the communication was last updated, in ISO 8601 format.

Delivery status values

The deliveryStatus field on each recipient has one of the following values:

Value	Description
`INITIATED`	The communication is queued to send.
`IN_PROGRESS`	The communication is being sent.
`DELIVERED`	The provider confirms delivery.
`COMPLETED`	For voice, the call has ended. For messaging, the recipient has read the message.
`FAILED`	The communication couldn't be sent or delivered.

Webhook payload examples

CONVERSATION_CREATED

1{
2  "eventType": "CONVERSATION_CREATED",
3  "timestamp": "2026-03-31T16:32:51.345476911Z",
4  "data": {
5    "id": "conv_conversation_01kn2bv81ne86bpt2ad7wafpqz",
6    "accountId": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
7    "configuration": {
8      "channelSettings": {
9        "SMS": {
10          "captureRules": [
11            {
12              "from": "*",
13              "to": "+15551234567",
14              "metadata": {}
15            },
16            {
17              "from": "+15551234567",
18              "to": "*",
19              "metadata": {}
20            }
21          ],
22          "statusTimeouts": {
23            "closed": 15,
24            "inactive": null
25          }
26        },
27        "VOICE": {
28          "captureRules": [],
29          "statusTimeouts": null
30        }
31      },
32      "conversationGroupingType": "GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE",
33      "description": "Configuration for support interactions",
34      "displayName": "support-conversations",
35      "intelligenceConfigurationIds": [],
36      "memoryExtractionEnabled": true,
37      "memoryStoreId": "mem_store_01kfp5sj35ecqsvff0b2vn77wr",
38      "redaction": null,
39      "statusCallbacks": [
40        {
41          "url": "https://example.com/webhook",
42          "method": "POST"
43        }
44      ]
45    },
46    "configurationId": "conv_configuration_01km10y03se0dakjayz4vnxybc",
47    "createdAt": "2026-03-31T16:32:51.254049339Z",
48    "name": "Auto-generated conversation",
49    "status": "ACTIVE",
50    "updatedAt": "2026-03-31T16:32:51.254049558Z"
51  }
52}

PARTICIPANT_ADDED

1{
2  "eventType": "PARTICIPANT_ADDED",
3  "timestamp": "2026-03-31T16:32:51.346215804Z",
4  "data": {
5    "id": "conv_participant_01kn2bv81nfh9826g8cthk73ak",
6    "conversationId": "conv_conversation_01kn2bv81ne86bpt2ad7wafpqz",
7    "accountId": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
8    "name": "+15559876543",
9    "addresses": [
10      {
11        "channel": "SMS",
12        "address": "+15559876543",
13        "channelId": null
14      }
15    ],
16    "createdAt": null,
17    "profileId": "mem_profile_01kg5rdy0af2jtrjfr7vpxsaad",
18    "type": "CUSTOMER",
19    "updatedAt": null
20  }
21}

COMMUNICATION_CREATED

1{
2  "eventType": "COMMUNICATION_CREATED",
3  "timestamp": "2026-03-31T16:32:51.353676996Z",
4  "data": {
5    "id": "conv_communication_01kn2bv81ff44r5h81ar7r1z69",
6    "conversationId": "conv_conversation_01kn2bv81ne86bpt2ad7wafpqz",
7    "accountId": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
8    "author": {
9      "address": "+15559876543",
10      "channel": "SMS",
11      "participantId": "conv_participant_01kn2bv81nfh9826g8cthk73ak"
12    },
13    "content": {
14      "type": "TEXT",
15      "text": "Hello, I need help with my order"
16    },
17    "recipients": [
18      {
19        "address": "+15551234567",
20        "channel": "SMS",
21        "participantId": "conv_participant_01kn2bv81nfvfr1j2mdesj84z2",
22        "deliveryStatus": "DELIVERED"
23      }
24    ],
25    "channelId": "SM5f4c40fd4643b8394bc0fe83e3d20ca9",
26    "createdAt": "2026-03-31T16:32:51.343567735Z",
27    "occurredAt": "2026-03-31T16:32:51.247963992Z",
28    "updatedAt": "2026-03-31T16:32:51.343573651Z"
29  }
30}

Next steps

Core concepts: The object model for conversations, participants, and communications.
Conversation lifecycle: How conversations move between ACTIVE, INACTIVE, and CLOSED.
Conversation Orchestrator API reference: Full API details for webhooks and status callbacks.