Skip to contentSkip to navigationSkip to topbar
On this page

Conversations Webhooks


Conversations sends pre-action and post-action webhooks for most events that happen in your application. These webhooks allow you to monitor and intercept user actions in your own backend service, in a Function, or in a Studio flow. You can also use these webhooks to store activity logs in a system of record or in a logging server as part of your own application.

(information)

Info

Conversations webhooks have a maximum timeout of 5 seconds.

(information)

Info

Twilio can send your web application an HTTP request when certain events happen, such as an incoming text message to one of your Twilio phone numbers. These requests are called webhooks, or status callbacks. For more, check out our guide to Getting Started with Twilio Webhooks. Find other webhook pages, such as a security guide and an FAQ in the Webhooks section of the docs.


Table of Contents

table-of-contents page anchor

Configuring Webhook Targets and Filtering

configuring-webhook-targets-and-filtering page anchor

You can configure the global (Account-level) webhook target and service-level webhook target through the Console, or through the REST API.

  • For the global webhook target, go to Conversations > Global webhooks.
  • For the service-level webhook target, select your Conversation Service, then go to Webhooks.
Configuring global webhooks for Conversations in the Twilio Console.

Note: The Conversation-scoped webhooks may only be modified via the REST API.

Webhook Filtering

webhook-filtering page anchor

In addition to configuring the URLs for pre-action and post-action webhooks, you can also choose to send only certain webhooks to your servers. This helps avoid unnecessarily burdening your web application with traffic.

These can also be configured at an account level (globally) or at the service level in the Twilio Console:

  • For the global webhook target, go to Conversations > Global webhooks and scroll down to Webhook Filtering.
  • For the service-level webhook target, select your Conversation Service, then go to Webhooks. Scroll down to Webhook Filtering.
Webhook Filtering Conversations.

Most actions — but not all of them — have both a pre-action and a post-action webhook. The former is fired before the action has been published, and Twilio waits for a response before publishing it. The latter is fired after publication, assuming the action was not rejected by your pre-action webhook response.

The below table enumerates all Conversations webhook actions in corresponding pairs.

Pre-ActionPost-ActionDescription (incl. Post-Action)
onMessageAddonMessageAddedFires when a new message is posted to a conversation.
onMessageRemoveonMessageRemovedFires when a message is deleted from a conversation.
onMessageUpdateonMessageUpdatedFires when a posted message's body or any attribute is changed.
onConversationAddonConversationAddedFires when a new conversation is created.
onConversationRemoveonConversationRemovedFires when a conversation is removed from the Service.
onConversationUpdateonConversationUpdatedFires when any attribute of a conversation is changed.
onParticipantAddonParticipantAddedFires when a Participant has joined a Conversation as a Member.
onParticipantRemoveonParticipantRemovedFires when a User is removed from the set of Conversation Members.
onParticipantUpdateonParticipantUpdatedFires when any configurable attribute of a User is changed. Will not be fired for reachability events.
---onConversationStateUpdatedFires when the state of a Conversation is updated, e.g., from "active" to "inactive"
---onDeliveryUpdatedFires when delivery receipt status is updated
---onUserAddedFires when a new user is added
onUserUpdateonUserUpdatedFires when a user is changed

Triggering Webhooks for REST API Events

triggering-webhooks-for-rest-api-events page anchor

Upon configuration, only actions from SDK-driven clients (like mobile phones or browsers) or SMS-based Participants will cause webhooks without further action on your part. This includes both Service-level webhooks and Conversation-Scoped Webhooks. This is a default behavior to help avoid infinite feedback loops.

Your Post-Event Webhook target, however, may be an important tool for archiving. In this case, you may also want to enable webhook "echoes" from actions you take on the REST API. To do so, you can add a header X-Twilio-Webhook-Enabled=true to any such request. Requests bearing this header will yield webhooks to the configured Post-Event webhook target.

Using Pre-Action Webhooks to Modify or Reject Changes

using-pre-action-webhooks-to-modify-or-reject-changes page anchor

In the case of Pre-Action webhooks, Twilio will wait for a response from your service before publishing a result. The arrival, HTTP status code, and content of your response determines how Conversations will proceed.

Response Status CodeBodyResult
HTTP 200 OK{}(or no content)Conversations will publish the change unmodified.
HTTP 200 OK{ "body": "modified message" }

(See the list of modifiable fields.)
Conversations will publish the change with modifications as given in the response.

All values are optional, and missing fields will be left unmodified from the original event. See below for which fields can be modified for each data type (Conversations or Messages).

If modified values fail validation, the error will be returned to the SDK (or REST client) that triggered the event.
HTTP 40x (any error condition)N/AConversations will reject the change and no publication will be made.
HTTP 50x (any error condition)N/AConversations will reject the change and no publication will be made.
(no response or timeout)Conversations will publish the change unmodified after a timeout of 5 seconds; your messages will be delayed accordingly.

Conversation Actions

conversation-actions page anchor

In response to the onConversationAdd and onConversationUpdate actions, your Pre-Action Webhook response may modify the following property of the conversation:

  • friendly_name

An example response modifying a conversation

1
HTTP 200 OK
2
Content-Type: application/json
3
{
4
"friendly_name": "friendly name of conversation"
5
}

In response to onMessageAdd and onMessageUpdate actions, your Pre-Action Webhook response may modify the following properties of the message:

  • body
  • author
  • attributes

An example response modifying a message.

1
HTTP 200 OK
2
Content-Type: application/json
3
{
4
"body": "modified message text",
5
"author": "modified author name",
6
"attributes": "{\"key\" : \"value\"}"
7
}

Configuring Webhooks with the REST API

configuring-webhooks-with-the-rest-api page anchor

Your Conversations service can have global webhooks that apply to every conversation within the service, or you can specify webhooks per conversation.

Post-action webhooks are available for all three types of webhooks (global, service-level and conversation-scoped). Pre-action webhooks are only available for two types of webhooks (global and service-level).

Retrieve Existing Global Webhook Configuration for a Conversation ServiceLink to code sample: Retrieve Existing Global Webhook Configuration for a Conversation Service
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function fetchConfigurationWebhook() {
11
const webhook = await client.conversations.v1.configuration
12
.webhooks()
13
.fetch();
14
15
console.log(webhook.accountSid);
16
}
17
18
fetchConfigurationWebhook();

Output

1
{
2
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
"pre_webhook_url": "https://example.com/pre",
4
"post_webhook_url": "https://example.com/post",
5
"method": "GET",
6
"filters": [
7
"onMessageSend",
8
"onConversationUpdated"
9
],
10
"target": "webhook",
11
"url": "https://conversations.twilio.com/v1/Configuration/Webhooks"
12
}
Update Global Webhook Configuration for a Conversation ServiceLink to code sample: Update Global Webhook Configuration for a Conversation Service
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function updateConfigurationWebhook() {
11
const webhook = await client.conversations.v1.configuration
12
.webhooks()
13
.update({
14
filters: ["onMessageAdd", "onMessageUpdate", "onMessageRemove"],
15
method: "POST",
16
postWebhookUrl: "https://YOUR_APPLICATION.com/webhook",
17
preWebhookUrl: "https://YOUR_APPLICATION.com/webhook",
18
target: "webhook",
19
});
20
21
console.log(webhook.accountSid);
22
}
23
24
updateConfigurationWebhook();

Output

1
{
2
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
"pre_webhook_url": "https://YOUR_APPLICATION.com/webhook",
4
"post_webhook_url": "https://YOUR_APPLICATION.com/webhook",
5
"method": "POST",
6
"filters": [
7
"onConversationUpdated"
8
],
9
"target": "webhook",
10
"url": "https://conversations.twilio.com/v1/Configuration/Webhooks"
11
}
List the Scoped Webhooks for a ConversationLink to code sample: List the Scoped Webhooks for a Conversation
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function listConversationScopedWebhook() {
11
const webhooks = await client.conversations.v1
12
.conversations("ConversationSid")
13
.webhooks.list({ limit: 20 });
14
15
webhooks.forEach((w) => console.log(w.sid));
16
}
17
18
listConversationScopedWebhook();

Output

1
{
2
"meta": {
3
"page": 0,
4
"page_size": 5,
5
"first_page_url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks?PageSize=5&Page=0",
6
"previous_page_url": null,
7
"url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks?PageSize=5&Page=0",
8
"next_page_url": null,
9
"key": "webhooks"
10
},
11
"webhooks": [
12
{
13
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14
"conversation_sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15
"sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
16
"target": "webhook",
17
"configuration": {
18
"url": "https://example.com",
19
"method": "get",
20
"filters": [
21
"onMessageSent",
22
"onConversationDestroyed"
23
]
24
},
25
"date_created": "2016-03-24T21:05:50Z",
26
"date_updated": "2016-03-24T21:05:50Z",
27
"url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
28
},
29
{
30
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
31
"conversation_sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
32
"sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
33
"target": "trigger",
34
"configuration": {
35
"url": "https://example.com",
36
"method": "post",
37
"filters": [
38
"keyword1",
39
"keyword2"
40
]
41
},
42
"date_created": "2016-03-24T21:05:50Z",
43
"date_updated": "2016-03-24T21:05:50Z",
44
"url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
45
},
46
{
47
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
48
"conversation_sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
49
"sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
50
"target": "studio",
51
"configuration": {
52
"flow_sid": "FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
53
},
54
"date_created": "2016-03-24T21:05:50Z",
55
"date_updated": "2016-03-24T21:05:50Z",
56
"url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
57
}
58
]
59
}
Retrieve the Configuration for a Specific WebhookLink to code sample: Retrieve the Configuration for a Specific Webhook
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function fetchConversationScopedWebhook() {
11
const webhook = await client.conversations.v1
12
.conversations("ConversationSid")
13
.webhooks("WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
14
.fetch();
15
16
console.log(webhook.sid);
17
}
18
19
fetchConversationScopedWebhook();

Output

1
{
2
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
"conversation_sid": "ConversationSid",
4
"sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5
"target": "studio",
6
"configuration": {
7
"flow_sid": "FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
8
},
9
"date_created": "2016-03-24T21:05:50Z",
10
"date_updated": "2016-03-24T21:05:50Z",
11
"url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
12
}
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function createConversationScopedWebhook() {
11
const webhook = await client.conversations.v1
12
.conversations("ConversationSid")
13
.webhooks.create({
14
"configuration.filters": ["onMessageAdded", "onMessageUpdated"],
15
"configuration.url": "https://YOUR_APPLICATION.com/webhook",
16
target: "webhook",
17
});
18
19
console.log(webhook.sid);
20
}
21
22
createConversationScopedWebhook();

Output

1
{
2
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
"conversation_sid": "ConversationSid",
4
"sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5
"target": "webhook",
6
"configuration": {
7
"url": "https://example.com",
8
"method": "get",
9
"filters": [
10
"onMessageSent",
11
"onConversationDestroyed"
12
]
13
},
14
"date_created": "2016-03-24T21:05:50Z",
15
"date_updated": "2016-03-24T21:05:50Z",
16
"url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
17
}

Webhook Bodies by Event Type

webhook-bodies page anchor

When Twilio makes an HTTP request to your server, it includes information about the action that triggered the webhook call to your web application. Each action has its own event type.

In addition to the event-specific parameters, each request also contains the following parameters and information:

parameter nametypedescription
AccountSidstring, SIDThe Twilio Account SID that the Conversation belongs to
EventTypestringThe type of action that triggered this webhook event (see details for each event type below)
SourcestringThe source of the action that created this event - possible values are SDK or API
ClientIdentitystringThe identity of the user that performed the action (SDK-originating events only)

Note: Each HTTP request is issued with the Content-Type header application/x-www-urlencoded.

Pre-action Webhooks Request Parameters

pre-action-webhooks page anchor

You may modify the FriendlyName of this conversation by replying to this webhook with a JSON object that contains the new friendly name.

parameter nametypedescription
EventTypestringAlways onConversationAdd
FriendlyNamestring, optionalThe friendly name of the conversation, if set
UniqueNamestringThe unique name of the conversation
AttributesstringConversation metadata as set by the customer, represented as stringified JSON
ChatServiceSidstring, SIDConversation Service SID
MessagingServiceSidstring, SIDMessaging Service instance SID
MessagingBinding.ProxyAddressstring, optional (see note)Twilio Brand phone number used by channel creator
MessagingBinding.Addressstring, optional (see note)Originating phone number of the channel creator
MessagingBinding.ProjectedAddressstring, optional*The address of the Twilio phone number that is used in Group MMS. Communication mask for the Conversation participant with Identity
MessagingBinding.AuthorAddressstring, optional*Number of the message author when auto-creating Group MMS
MessageBodystring, optionalInitial conversation message string
Mediastring, JSON, optionalStringified JSON array of attached media objects
StatestringEnumerated type representing state of the conversation
ChannelMetadatastringStringified and escaped JSON pass-through metadata from OTT channels. Only available for GBM. See sample payload.

Note: MessagingBinding.ProxyAddress and MessagingBinding.Address attributes are null if the Conversation is created from the REST API and there are no participants yet. Note: When auto-creating Group MMS Conversation, MessagingBinding.Address is shown as a list of Addresses.

parameter nametypedescription
EventTypestringAlways onConversationRemove
ConversationSidstring, SIDConversation String Identifier
DateCreatedstring, ISO8601 timeThe date of creation of the conversation
DateUpdatedstring, ISO8601 timeThe last modification date of the conversation
FriendlyNamestring, optionalThe friendly name of the conversation, if set
UniqueNamestringThe unique name of the conversation
AttributesstringConversation metadata as set by the customer, represented as stringified JSON
ChatServiceSidstring, SIDConversation Service SID
MessagingServiceSidstring, SIDMessaging Service instance SID
StatestringEnumerated type representing state of the conversation

You may modify the FriendlyName of this conversation by replying to this webhook with a JSON object that contains the new friendly name.

parameter nametypedescription
EventTypestringAlways onConversationUpdate
ConversationSidstring, SIDConversation String Identifier
DateCreatedstring, ISO8601 timeThe date of creation of the conversation
DateUpdatedstring, ISO8601 timeThe last modification date of the conversation
FriendlyNamestring, optionalThe friendly name of the conversation, if set
UniqueNamestringThe unique name of the conversation
AttributesstringConversation metadata as set by the customer, represented as stringified JSON
ChatServiceSidstring, SIDConversation Service SID
MessagingServiceSidstring, SIDMessaging Service instance SID
StatestringEnumerated type representing state of the conversation

Your application may modify the Body and Author parameters in the pre-event webhook. To update these parameters, reply to the webhook with a JSON object that contains the relevant keys and values.

parameter nametypedescription
EventTypestringAlways onMessageAdd
ConversationSidstringConversation SID identifier for the conversation the message is being added to.
BodystringThe body of the message
AuthorstringThe author of the message
ParticipantSidstring, optionalParticipant SID of the message author
AttributesstringMessage metadata as set by customer, represented as stringified JSON
Mediastring, JSON, optionalStringified JSON array of attached media objects
ChannelMetadatastringStringified and escaped JSON pass-through metadata from OTT channels. Only available for GBM. See sample payload.
parameter nametypedescription
EventTypestringAlways onMessageRemove
ConversationSidstringConversation SID identifier for the conversation the message is being removed from.
MessageSidstringMessage sid identifier
IndexintMessage index in the messages stream
DateCreatedstring, ISO8601 timeCreation date of the message
DateUpdatedstring, ISO8601 timeLast modification date of the message
BodystringThe body of the message
AuthorstringThe author of the message
ParticipantSidString, optionalParticipant SID of the message author
AttributesstringMessage metadata as set by customer, represented as stringified JSON
Mediastring, JSON, optionalStringified JSON array of attached media objects

Your application may modify the Body and Authorparameters in the pre-event webhook. To update these parameters, reply to the webhook with a JSON object that contains the relevant keys and values.

parameter nametypedescription
EventTypestringAlways onMessageUpdate
ConversationSidstringConversation SID identifier for the conversation the message is in.
MessageSidstringMessage sid identifier
IndexintMessage index in the messages stream
DateCreatedstring, ISO8601 timeCreation date of the message
DateUpdatedstring, ISO8601 timeLast modification date of the message
BodystringThe body of the message
AuthorstringThe author of the message
ParticipantSidstring, optionalParticipant SID of the message author
AttributesstringMessage metadata as set by customer, represented as stringified JSON
Mediastring, JSON, optionalStringified JSON array of attached media objects
parameter nametypedescription
EventTypestringAlways onParticipantAdd
ConversationSidstring, SIDConversation String Identifier
Identitystring, optional (see note)The Identity of the user being added to the conversation
RoleSidstringRole of user that is being added to the conversation
AttributesstringParticipant metadata as set by the customer, represented as stringified JSON
MessagingBinding.ProxyAddressstring, optional (see note)Twilio Brand phone number used by participant
MessagingBinding.Addressstring, optional (see note)Originating phone number of the participant
MessagingBinding.ProjectedAddressstring, optional*The address of the Twilio phone number that is used in Group MMS. Communication mask for the Conversation participant with Identity
MessagingBinding.TypestringType of the participant, one of: SMS, CHAT, WHATSAPP

Note: A Conversation Participant has either the Identity (and MessagingBinding ProjectedAddress for GroupMMS Participant) or MessagingBinding ProxyAddress and Address attributes filled in. In case the added participant is SMS or WhatsApp, Identity is null and both addresses are supplied. If the added participant is Chat-only, the Identity value is provided, and both MessagingBinding addresses (MessagingBinding ProxyAddress and Address) are null.

parameter nametypedescription
EventTypestringAlways onParticipantRemove
ConversationSidstring, SIDConversation String Identifier
ParticipantSidstring, SIDParticipant String Identifier
DateCreatedstring, ISO8601 timeCreation date of the participant
DateUpdatedstring, ISO8601 timeThe last modification date of the participant
Identitystring, optional (see note)The Identity of the user being removed from the conversation
RoleSidstringRole of user that is being removed from the conversation
AttributesstringParticipant metadata as set by the customer, represented as stringified JSON
MessagingBinding.ProxyAddressstring, optional (see note)Twilio Brand phone number used by participant
MessagingBinding.Addressstring, optional (see note)Originating phone number of the participant
MessagingBinding.ProjectedAddressstring, optional*The address of the Twilio phone number that is used in Group MMS. Communication mask for the Conversation participant with Identity
MessagingBinding.TypestringType of the participant, one of: SMS, CHAT, WHATSAPP

Note: A Conversation Participant has either the Identity (and MessagingBinding ProjectedAddress for GroupMMS Participant) or MessagingBinding ProxyAddress and Address attributes filled in. In case the added participant is SMS or WhatsApp, Identity is null and both addresses are supplied. If the added participant is Chat-only, the Identity value is provided, and both MessagingBinding addresses (MessagingBinding ProxyAddress and Address) are null.

parameter nametypedescription
EventTypestringAlways onParticipantUpdate
ConversationSidstring, SIDConversation String Identifier
ParticipantSidstring, SIDParticipant String Identifier
DateCreatedstring, ISO8601 timeCreation date of the participant
DateUpdatedstring, ISO8601 timeThe last modification date of the participant
Identitystring, optional (see note)The Identity of the user being added to the conversation
RoleSidstringRole of the user that is being added to the conversation
AttributesstringParticipant metadata as set by the customer, represented as stringified JSON
MessagingBinding.ProxyAddressstring, optional (see note)Twilio Brand phone number used by participant
MessagingBinding.Addressstring, optional (see note)Originating phone number of the participant
MessagingBinding.ProjectedAddressstring, optional*The address of the Twilio phone number that is used in Group MMS. Communication mask for the Conversation participant with Identity
MessagingBinding.TypestringType of the participant, one of: SMS, CHAT, WHATSAPP

Note: A Conversation Participant has either the Identity (and MessagingBinding ProjectedAddress for GroupMMS Participant) or MessagingBinding ProxyAddress and Address attributes filled in. In case the added participant is SMS or WhatsApp, Identity is null and both addresses are supplied. If the added participant is Chat-only, the Identity value is provided, and both MessagingBinding addresses (MessagingBinding ProxyAddress and Address) are null.

parameter nametypedescription
EventTypestringAlways onUserUpdate
ChatServiceSidstring, SIDConversation Service String Identifier
UserSidString, SIDUser String Identifier
DateUpdatedstring, ISO8601 timeUser modification date
Identitystring, optional (see note)The Identity of the user being updated
RoleSidstringRole of the user being updated
AttributesstringUser metadata, as set by the customer, represented as stringified JSON
FriendlyNamestringFriendly name of the User

Post Action Webhooks request parameters

post-action-webhooks page anchor
parameter nametypedescription
EventTypestringAlways onConversationAdded
ConversationSidstring, SIDConversation Sid identifier
DateCreatedstring, ISO8601 timeThe date of creation of the conversation
DateUpdatedstring, ISO8601 timeThe last modification date of the conversation
FriendlyNamestring, optionalThe friendly name of the conversation, if set
UniqueNamestring, optionalThe unique name of the conversation
AttributesstringConversation metadata as set by the customer, represented as stringified JSON
ChatServiceSidstring, SIDConversation Service SID
MessagingServiceSidstring, SIDMessaging Service instance SID
MessagingBinding.ProxyAddressstring, optional (see note)Twilio Brand phone number used by channel creator
MessagingBinding.Addressstring, optional (see note)Originating phone number of the channel creator
MessagingBinding.ProjectedAddressstring, optional*The address of the Twilio phone number that is used in Group MMS. Communication mask for the Conversation participant with Identity
MessagingBinding.AuthorAddressstring, optional*Number of the message author when auto-creating Group MMS
StatestringEnumerated type representing state of the conversation
ChannelMetadatastringStringified and escaped JSON pass-through metadata from OTT channels. Only available for GBM. See sample payload.
parameter nametypedescription
EventTypestringAlways onConversationRemoved
ConversationSidstring, SIDConversation String Identifier
DateCreatedstring, ISO8601 timeThe date of creation of the conversation
DateUpdatedstring, ISO8601 timeThe last modification date of the conversation
DateRemovedstring, ISO8601 timeThe date the conversation was removed
FriendlyNamestring, optionalThe friendly name of the conversation, if set
UniqueNamestring, optionalThe unique name of the conversation
AttributesstringConversation metadata as set by the customer, represented as stringified JSON
ChatServiceSidstring, SIDConversation Service SID
MessagingServiceSidstring, SIDMessaging Service instance SID
StatestringEnumerated type representing state of the conversation

You may modify the FriendlyName of this conversation by replying to this webhook with a JSON object that contains the new friendly name.

parameter nametypedescription
EventTypestringAlways onConversationUpdated
ConversationSidstring, SIDConversation String Identifier
DateCreatedstring, ISO8601 timeThe date of creation of the conversation
DateUpdatedstring, ISO8601 timeThe last modification date of the conversation
FriendlyNamestring, optionalThe friendly name of the conversation, if set
UniqueNamestring, optionalThe unique name of the conversation
AttributesstringConversation metadata as set by the customer, represented as stringified JSON
ChatServiceSidstring, SIDConversation Service SID
MessagingServiceSidstring, SIDMessaging Service instance SID
StatestringEnumerated type representing state of the conversation

onConversationStateUpdated

onconversationstateupdated page anchor
parameter nametypedescription
EventTypestringonConversationStateUpdated
ChatServiceSidstring, SIDConversation Service SID
StateUpdatedstring, ISO8601 timeModification date of the state
StateFromStringState that conversation was transitioned from, e.g. "active", "inactive" or "closed".
StateToStringState that conversation was transitioned to, e.g. "active", "inactive" or "closed".
ConversationSidString, SIDConversation String Identifier
ReasonStringSource of the state change, e.g., "API", "TIMER", "EVENT"
MessagingServiceSidString, SIDMessaging Service SID
parameter nametypedescription
EventTypestringAlways onMessageAdded
ConversationSidstringConversation SID identifier for the conversation the message is being added to.
MessageSidstringMessage sid identifier
MessagingServiceSidstring, SIDThe Messaging Service SID attached to the conversation this message is being added to.
IndexintMessage index in the messages stream
DateCreatedstring, ISO8601 timeCreation date of the message
BodystringThe body of the message
AuthorstringThe author of the message
ParticipantSidstring, optionalParticipant SID of the message author
AttributesstringMessage metadata as set by customer, represented as stringified JSON
Mediastring, JSON, optionalStringified JSON array of attached media objects
ChannelMetadatastringStringified and escaped JSON pass-through metadata from OTT channels. Only available for GBM. See sample payload.
parameter nametypedescription
EventTypestringAlways onMessageUpdated
ConversationSidstringConversation SID identifier for the conversation the message is in.
MessageSidstringMessage sid identifier
IndexintMessage index in the messages stream
DateCreatedstring, ISO8601 timeCreation date of the message
DateUpdatedstring, ISO8601 timeLast modification date of the message
BodystringThe body of the message
AuthorstringThe author of the message
ParticipantSidstring, optionalParticipant SID of the message author
AttributesstringMessage metadata as set by customer, represented as stringified JSON
Mediastring, JSON, optionalStringified JSON array of attached media objects
parameter nametypedescription
EventTypestringAlways onMessageRemoved
ConversationSidstringConversation SID identifier for the conversation the message was removed from.
MessageSidstringMessage sid identifier
IndexintMessage index in the messages stream
DateCreatedstring, ISO8601 timeCreation date of the message
DateUpdatedstring, ISO8601 timeLast modification date of the message
DateRemovedstring, ISO8601 timeDate that the message was removed from the conversation
BodystringThe body of the message
AuthorstringThe author of the message
ParticipantSidstring, optionalParticipant SID of the message author
AttributesstringMessage metadata as set by customer, represented as stringified JSON
Mediastring, JSON, optionalStringified JSON array of attached media objects
parameter nametypedescription
EventTypestringAlways onParticipantAdded
ConversationSidstring, SIDConversation String Identifier
ParticipantSidstring, SIDParticipant String Identifier
DateCreatedstring, ISO8601 timeThe date of creation of the participant
Identitystring, optional (see note)The Identity of the user being added to the conversation
RoleSidstringRole of user that is being added to the conversation
AttributesstringParticipant metadata as set by the customer, represented as stringified JSON
MessagingBinding.ProxyAddressstring, optional (see note)Twilio Brand phone number used by participant
MessagingBinding.Addressstring, optional (see note)Originating phone number of the participant
MessagingBinding.ProjectedAddressstring, optional*The address of the Twilio phone number that is used in Group MMS
MessagingBinding.TypestringType of the participant, one of: SMS, CHAT, WHATSAPP

Note: A Conversation Participant has either the Identity (and MessagingBinding ProjectedAddress for GroupMMS Participant) or MessagingBinding ProxyAddress and Address attributes filled in. In case the added participant is SMS or WhatsApp, Identity is null and both addresses are supplied. If the added participant is Chat-only, the Identity value is provided, and both MessagingBinding addresses (MessagingBinding ProxyAddress and Address) are null.

parameter nametypedescription
EventTypestringAlways onParticipantRemoved
ConversationSidstring, SIDConversation String Identifier
ParticipantSidstring, SIDParticipant String Identifier
DateCreatedstring, ISO8601 timeCreation date of the participant
DateUpdatedstring, ISO8601 timeThe last modification date of the participant
DateRemovedstring, ISO8601 timeThe date the participant was removed
Identitystring, optional (see note)The Identity of the user being removed from the conversation
RoleSidstringRole of user that is being removed from the conversation
AttributesstringParticipant metadata as set by the customer, represented as stringified JSON
MessagingBinding.ProxyAddressstring, optional (see note)Twilio Brand phone number used by participant
MessagingBinding.Addressstring, optional (see note)Originating phone number of the participant
MessagingBinding.ProjectedAddressstring, optional*The address of the Twilio phone number that is used in Group MMS
MessagingBinding.TypestringType of the participant, one of: SMS, CHAT, WHATSAPP

Note: A Conversation Participant has either the Identity (and MessagingBinding ProjectedAddress for GroupMMS Participant) or MessagingBinding ProxyAddress and Address attributes filled in. In case the added participant is SMS or WhatsApp, Identity is null and both addresses are supplied. If the added participant is Chat-only, the Identity value is provided, and both MessagingBinding addresses (MessagingBinding ProxyAddress and Address) are null.

parameter nametypedescription
EventTypestringAlways onParticipantUpdated
ConversationSidstring, SIDConversation String Identifier
ParticipantSidstring, SIDParticipant String Identifier
DateCreatedstring, ISO8601 timeCreation date of the participant
DateUpdatedstring, ISO8601 timeThe last modification date of the participant
Identitystring, optional (see note)The Identity of the user being added to the conversation
RoleSidstringRole of user that is being added to the conversation
AttributesstringParticipant metadata as set by the customer, represented as stringified JSON
MessagingBinding.ProxyAddressstring, optional (see note)Twilio Brand phone number used by participant
MessagingBinding.Addressstring, optional (see note)Originating phone number of the participant
MessagingBinding.ProjectedAddressstring, optional*The address of the Twilio phone number that is used in Group MMS
MessagingBinding.TypestringType of the participant, one of: SMS, CHAT, WHATSAPP
LastReadMessageIndexintIndex of last "read" message in the Conversation for the participant

Note: A Conversation Participant has either the Identity (and MessagingBinding ProjectedAddress for GroupMMS Participant) or MessagingBinding ProxyAddress and Address attributes filled in. In case the added participant is SMS or WhatsApp, Identity is null and both addresses are supplied. If the added participant is Chat-only, the Identity value is provided, and both MessagingBinding addresses (MessagingBinding ProxyAddress and Address) are null.

parameter nametypedescription
EventTypestringonDeliveryUpdated
AccountSidstring, SIDSID of the account that the message belongs to, ACxx
ConversationSidstring, SIDConversation String Identifier, CHxx
ChatServiceSidstring, SIDConversation Service SID, ISxx
MessageSidstring, SIDIdentifier of Conversation Message, IMxxx
DeliveryReceiptSidstring, SIDSID of the Delivery Receipt, DYxx
ChannelMessageSidstring, SIDSID of the 'channel' message e.g WAxx for WhatsApp, SMxx for SMS
ParticipantSidstring, SIDParticipant String Identifier, MBxx
Statusstring, enumStatus of the message, one of "read", "failed", "delivered", "undelivered", "sent"
ErrorCodeintegerTwilio documented numeric error code
DateCreatedstring, ISO8601 timeDate delivery receipt was created
DateUpdatedstring, ISO8601 timeDate that delivery receipt was last created
parameter nametypedescription
EventTypestringAlways onUserAdded
ChatServiceSidstring, SIDConversation Service String Identifier
UserSidstring, SIDString identifier of newly created User
DateCreatedstring, ISO8601 timeThe date of creation of the User
Identitystring, optional (see note)The Identity of the user being added to the conversation
RoleSidstringRole of the user that is being added to the conversation
AttributesstringUser metadata as set by the customer, represented as stringified JSON
FriendlyNamestringFriendly name of the User
parameter nametypedescription
EventTypestringAlways onUserUpdated
ChatServiceSidstring, SIDConversation Service String Identifier
UserSidstring, SIDUser String Identifier
DateCreatedstring, ISO8601 timeThe date of creation of the User
DateUpdatedstring, ISO8601 timeUser modification date
Identitystring, optional (see note)The Identity of the user being added to the conversation
RoleSidstringRole of the user that was updated
AttributesstringUser metadata as set by the customer, represented as stringified JSON
FriendlyNamestringFriendly name of the User
isOnlineBooleanWhether the User is actively connected to this Conversations Service and online
isNotifiableBooleanWhether the User has a potentially valid Push Notification registration (APN or GCM) for this Conversations Service

Channel Metadata JSON Sample

channel-metadata-json-sample page anchor

Pass-through metadata from the OTT channel. Currently, only supported for Google Business Messages. The channel key (gbm) is always available, but the values passed inside are set by Google and are subject to change.

(error)

End of Life

Google Business Messages (GBM) will be turned off on July 31, 2024. The Twilio GBM API and Google Business Profiles chat will no longer work after that point.

Learn more about the GBM End of Life from Google(link takes you to an external page).

1
"ChannelMetadata": "{
2
\"gbm\": {
3
\"context\": {
4
\"placeId\": \"ChIJU6DUSUUVkCQRxl6dlKFV8ok\",
5
\"entryPoint\": \"PLACESHEET\",
6
\"userInfo\": { \"displayName\": \"Sample Name\", \"userDeviceLocale\": \"en-US\" },
7
\"resolvedLocale\": \"en\"
8
}
9
}
10
}"

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.