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.
You can configure the global (Service-level) webhooks through the Console, or through the REST API.
Note: The Conversation-scoped webhooks may only be modified via the REST API.
In addition to configuring the URLs for pre-action and post-action webhooks, you can choose to send only certain webhooks to your servers. This helps avoid unnecessarily burdening your web application with traffic.
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.
Webhook Action Triggers
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-Action | Post-Action | Description (incl. Post-Action) |
onMessageAdd |
onMessageAdded |
Fires when a new message is posted to a conversation. |
onMessageRemove |
onMessageRemoved |
Fires when a message is deleted from a conversation. |
onMessageUpdate |
onMessageUpdated |
Fires when a posted message's body or any attribute is changed. |
onConversationAdd |
onConversationAdded |
Fires when a new conversation is created. |
onConversationUpdate |
onConversationUpdated |
Fires when any attribute of a conversation is changed. |
onConversationRemove |
onConversationRemoved |
Fires when a conversation is removed from the Service. |
onParticipantAdd |
onParticipantAdded |
Fires when a Participant has joined a Conversation as a Member. |
onParticipantRemove |
onParticipantRemoved |
Fires when a User is removed from the set of Conversation Members. |
onParticipantUpdate |
onParticipantUpdated |
Fires when any configurable attribute of a User is changed. Will not be fired for reachability events. |
| --- | onConversationStateUpdated |
Fires when the state of a Conversation is updated, e.g., from "active" to "inactive" |
| --- | onDeliveryUpdated |
Fires when delivery receipt status is updated |
Triggering Webhooks for REST API Events
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
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 Code | Body | result |
| HTTP 200 OK | {} (or no content) |
Conversations will publish the change unmodified. |
| HTTP 200 OK |
|
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) | 該当なし | Conversations will reject the change and no publication will be made. |
| HTTP 50x (any error condition) | 該当なし | Conversations will reject the change and no publication will be made. |
| (no response or timeout) | Conversations will publish the change unmodified after a series of retries; your messages will be delayed accordingly. |
Modifiable Fields
Conversation Actions
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
HTTP 200 OK
Content-Type: text/json
{
"friendly_name": "friendly name of conversation"
}
Message Actions
In response to onMessageAdd and onMessageUpdate actions, your Pre-Action Webhook response may modify the following properties of the message:
bodyauthor
An example response modifying a message.
HTTP 200 OK
Content-Type: text/json
{
"body": "modified message text",
"author": "modified author name"
}
Configuring Webhooks with the REST API
Your Conversations service can have global webhooks that apply to every conversation within the service, or you can specify webhooks per conversation.
If you would like to use pre-action webhooks, those must be specified as global webhooks. Post-action webhooks may be consumed by either global or conversation-specific webhooks.
Webhook Bodies by Event Type
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:
| パラメーター名 | タイプ | description |
|---|---|---|
| AccountSid | string, SID | The Twilio Account SID |
| EventType | 文字列 | One of the known webhook types. Each of these string values is documented in the corresponding section. |
Note: Each HTTP request is issued with the Content-Type header application/x-www-urlencoded.
Pre-action Webhooks Request Parameters
onConversationAdd
You may modify the FriendlyName of this conversation by replying to this webhook with a JSON object that contains the new friendly name.
| パラメーター名 | タイプ | description |
|---|---|---|
| EventType | 文字列 | Always onConversationAdd |
| FriendlyName | 文字列、オプション | The friendly name of the conversation, if set |
| ChatServiceSid | string, SID | Chat Service instance SID |
| MessagingServiceSid | string, SID | Messaging Service instance SID |
| MessagingBinding.ProxyAddress | string, optional (see note) | Twilio Brand phone number used by channel creator |
| MessagingBinding.Address | string, optional (see note) | Originating phone number of the channel creator |
| MessageBody | 文字列、オプション | Initial conversation message string |
注 : MessagingBinding.ProxyAddress and MessagingBinding.Address attributes are null if the Conversation is created from the REST API and there are no participants yet.
onConversationRemove
| パラメーター名 | タイプ | description |
|---|---|---|
| EventType | 文字列 | Always onConversationRemove |
| ConversationSid | string, SID | Conversation String Identifier |
| DateCreated | string, ISO8601 time | The date of creation of the conversation |
| DateUpdated | string, ISO8601 time | The last modification date of the conversation |
| FriendlyName | 文字列、オプション | The friendly name of the conversation, if set |
| ChatServiceSid | string, SID | Chat Service instance SID |
| MessagingServiceSid | string, SID | Messaging Service instance SID |
onConversationUpdate
You may modify the FriendlyName of this conversation by replying to this webhook with a JSON object that contains the new friendly name.
| パラメーター名 | タイプ | description |
|---|---|---|
| EventType | 文字列 | Always onConversationUpdate |
| ConversationSid | string, SID | Conversation String Identifier |
| DateCreated | string, ISO8601 time | The date of creation of the conversation |
| DateUpdated | string, ISO8601 time | The last modification date of the conversation |
| FriendlyName | 文字列、オプション | The friendly name of the conversation, if set |
| ChatServiceSid | string, SID | Chat Service instance SID |
| MessagingServiceSid | string, SID | Messaging Service instance SID |
onMessageAdd
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.
| パラメーター名 | タイプ | description |
|---|---|---|
| EventType | 文字列 | Always onMessageAdd |
| ConversationSid | 文字列 | Conversation SID identifier for the conversation the message is being added to. |
| Body | 文字列 | The body of the message |
| Author | 文字列 | メッセージの作成者 |
| ParticipantSid | 文字列、オプション | Participant SID of the message author |
OnMessageUpdate
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.
| パラメーター名 | タイプ | description |
|---|---|---|
| EventType | 文字列 | Always onMessageUpdate |
| ConversationSid | 文字列 | Conversation SID identifier for the conversation the message is in. |
| Message SID | 文字列 | Message sid identifier |
| index | int | Message index in the messages stream |
| DateCreated | string, ISO8601 time | Creation date of the message |
| DateUpdated | string, ISO8601 time | Last modification date of the message |
| Body | 文字列 | The body of the message |
| Author | 文字列 | メッセージの作成者 |
| ParticipantSid | 文字列、オプション | Participant SID of the message author |
OnMessageRemove
| パラメーター名 | タイプ | description |
|---|---|---|
| EventType | 文字列 | Always onMessageRemove |
| ConversationSid | 文字列 | Conversation SID identifier for the conversation the message is being removed from. |
| Message SID | 文字列 | Message sid identifier |
| index | int | Message index in the messages stream |
| DateCreated | string, ISO8601 time | Creation date of the message |
| DateUpdated | string, ISO8601 time | Last modification date of the message |
| Body | 文字列 | The body of the message |
| Author | 文字列 | メッセージの作成者 |
| ParticipantSid | String, optional | Participant SID of the message author |
onParticipantAdd
| パラメーター名 | タイプ | description |
|---|---|---|
| EventType | 文字列 | Always onParticipantAdd |
| ConversationSid | string, SID | Conversation String Identifier |
| Identity | string, optional (see note) | The Identity of the Chat User being added to the conversation |
| MessagingBinding.ProxyAddress | string, optional (see note) | Twilio Brand phone number used by participant |
| MessagingBinding.Address | string, optional (see note) | Originating phone number of the participant |
| MessagingBinding.Type | 文字列 | Type of the participant, one of: SMS, CHAT, WHATSAPP |
Note: A Conversation Participant has either the Identity 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 are null.
onParticipantRemove
| パラメーター名 | タイプ | description |
|---|---|---|
| EventType | 文字列 | Always onParticipantRemove |
| ConversationSid | string, SID | Conversation String Identifier |
| ParticipantSid | string, SID | Participant String Identifier |
| DateCreated | string, ISO8601 time | Creation date of the participant |
| DateUpdated | string, ISO8601 time | The last modification date of the participant |
| Identity | string, optional (see note) | The Identity of the Chat User being added to the conversation |
| MessagingBinding.ProxyAddress | string, optional (see note) | Twilio Brand phone number used by participant |
| MessagingBinding.Address | string, optional (see note) | Originating phone number of the participant |
| MessagingBinding.Type | 文字列 | Type of the participant, one of: SMS, CHAT, WHATSAPP |
Note: A Conversation Participant has either the Identity or MessagingBinding.ProxyAddress and MessagingBinding.Address attributes supplied. 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 are null.
onParticipantUpdate
| パラメーター名 | タイプ | description |
|---|---|---|
| EventType | 文字列 | Always onParticipantUpdate |
| ConversationSid | string, SID | Conversation String Identifier |
| ParticipantSid | string, SID | Participant String Identifier |
| DateCreated | string, ISO8601 time | Creation date of the participant |
| DateUpdated | string, ISO8601 time | The last modification date of the participant |
| Identity | string, optional (see note) | The Identity of the Chat User being added to the conversation |
| MessagingBinding.ProxyAddress | string, optional (see note) | Twilio Brand phone number used by participant |
| MessagingBinding.Address | string, optional (see note) | Originating phone number of the participant |
| MessagingBinding.Type | 文字列 | Type of the participant, one of: SMS, CHAT, WHATSAPP |
Note: Participant has either Identity or MessagingBinding.ProxyAddress and MessagingBinding.Address attributes supplied. 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 are null.
Post Action Webhooks request parameters
onConversationAdded
| パラメーター名 | タイプ | description |
|---|---|---|
| EventType | 文字列 | Always onConversationAdded |
| ConversationSid | string, SID | Conversation Sid identifier |
| DateCreated | string, ISO8601 time | The date of creation of the conversation |
| FriendlyName | 文字列、オプション | The friendly name of the conversation, if set |
| ChatServiceSid | string, SID | Chat Service instance SID |
| MessagingServiceSid | string, SID | Messaging Service instance SID |
onConversationRemoved
| パラメーター名 | タイプ | description |
|---|---|---|
| EventType | 文字列 | Always onConversationRemoved |
| ConversationSid | string, SID | Conversation String Identifier |
| DateCreated | string, ISO8601 time | The date of creation of the conversation |
| DateUpdated | string, ISO8601 time | The last modification date of the conversation |
| DateRemoved | string, ISO8601 time | The date the conversation was removed |
| FriendlyName | 文字列、オプション | The friendly name of the conversation, if set |
| ChatServiceSid | string, SID | Chat Service instance SID |
| MessagingServiceSid | string, SID | Messaging Service instance SID |
onConversationUpdated
You may modify the FriendlyName of this conversation by replying to this webhook with a JSON object that contains the new friendly name.
| パラメーター名 | タイプ | description |
|---|---|---|
| EventType | 文字列 | Always onConversationUpdated |
| ConversationSid | string, SID | Conversation String Identifier |
| DateCreated | string, ISO8601 time | The date of creation of the conversation |
| DateUpdated | string, ISO8601 time | The last modification date of the conversation |
| FriendlyName | 文字列、オプション | The friendly name of the conversation, if set |
| ChatServiceSid | string, SID | Chat Service instance SID |
| MessagingServiceSid | string, SID | Messaging Service instance SID |
onConversationStateUpdated
| パラメーター名 | タイプ | description |
|---|---|---|
| EventType | 文字列 | onConversationStateUpdated |
| StateUpdated | string, ISO8601 time | Modification date of the state |
| StateFrom | 文字列 | State that conversation was transitioned from, e.g. "active", "inactive" or "closed". |
| StateTo | 文字列 | State that conversation was transitioned to, e.g. "active", "inactive" or "closed". |
| ConversationSid | String, SID | Conversation String Identifier |
| reason | 文字列 | Source of the state change, e.g., "API", "TIMER", "EVENT" |
| MessagingServiceSid | String, SID | Messaging Service SID |
onMessageAdded
| パラメーター名 | タイプ | description |
|---|---|---|
| EventType | 文字列 | Always onMessageAdded |
| ConversationSid | 文字列 | Conversation SID identifier for the conversation the message is being added to. |
| Message SID | 文字列 | Message sid identifier |
| index | int | Message index in the messages stream |
| DateCreated | string, ISO8601 time | Creation date of the message |
| Body | 文字列 | The body of the message |
| Author | 文字列 | メッセージの作成者 |
| ParticipantSid | String, optional | Participant SID of the message author |
onMessageUpdated
| パラメーター名 | タイプ | description |
|---|---|---|
| EventType | 文字列 | Always onMessageUpdated |
| ConversationSid | 文字列 | Conversation SID identifier for the conversation the message is in. |
| Message SID | 文字列 | Message sid identifier |
| index | int | Message index in the messages stream |
| DateCreated | string, ISO8601 time | Creation date of the message |
| DateUpdated | string, ISO8601 time | Last modification date of the message |
| Body | 文字列 | The body of the message |
| Author | 文字列 | メッセージの作成者 |
| ParticipantSid | 文字列、オプション | Participant SID of the message author |
onMessageRemoved
| パラメーター名 | タイプ | description |
|---|---|---|
| EventType | 文字列 | Always onMessageRemoved |
| ConversationSid | 文字列 | Conversation SID identifier for the conversation the message was removed from. |
| Message SID | 文字列 | Message sid identifier |
| index | int | Message index in the messages stream |
| DateCreated | string, ISO8601 time | Creation date of the message |
| DateUpdated | string, ISO8601 time | Last modification date of the message |
| DateRemoved | string, ISO8601 time | Date that the message was removed from the conversation |
| Body | 文字列 | The body of the message |
| Author | 文字列 | メッセージの作成者 |
| ParticipantSid | 文字列、オプション | Participant SID of the message author |
onParticipantAdded
| パラメーター名 | タイプ | description |
|---|---|---|
| EventType | 文字列 | Always onParticipantAdded |
| ConversationSid | string, SID | Conversation String Identifier |
| ParticipantSid | string, SID | Participant String Identifier |
| DateCreated | string, ISO8601 time | The date of creation of the participant |
| Identity | string, optional (see note) | The Identity of the Chat User being added to the conversation |
| MessagingBinding.ProxyAddress | string, optional (see note) | Twilio Brand phone number used by participant |
| MessagingBinding.Address | string, optional (see note) | Originating phone number of the participant |
| MessagingBinding.Type | 文字列 | Type of the participant, one of: SMS, CHAT, WHATSAPP |
Note: Participant has either the Identity or MessagingBinding ProxyAddress and Address attributes filled in. If 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 are null.
onParticipantRemoved
| パラメーター名 | タイプ | description |
|---|---|---|
| EventType | 文字列 | Always onParticipantRemoved |
| ConversationSid | string, SID | Conversation String Identifier |
| ParticipantSid | string, SID | Participant String Identifier |
| DateCreated | string, ISO8601 time | Creation date of the participant |
| DateUpdated | string, ISO8601 time | The last modification date of the participant |
| DateRemoved | string, ISO8601 time | The date the participant was removed |
| Identity | string, optional (see note) | The Identity of the Chat User being added to the conversation |
| MessagingBinding.ProxyAddress | string, optional (see note) | Twilio Brand phone number used by participant |
| MessagingBinding.Address | string, optional (see note) | Originating phone number of the participant |
| MessagingBinding.Type | 文字列 | Type of the participant, one of: SMS, CHAT, WHATSAPP |
Note: Participant has either theIdentity or MessagingBinding.ProxyAddress and MessagingBinding.Address attributes supplied. If the added participant is Chat-only, the Identity value is provided, and both MessagingBinding addresses are null.
onParticipantUpdated
| パラメーター名 | タイプ | description |
|---|---|---|
| EventType | 文字列 | Always onParticipantUpdated |
| ConversationSid | string, SID | Conversation String Identifier |
| ParticipantSid | string, SID | Participant String Identifier |
| DateCreated | string, ISO8601 time | Creation date of the participant |
| DateUpdated | string, ISO8601 time | The last modification date of the participant |
| Identity | string, optional (see note) | The Identity of the Chat User being added to the conversation |
| MessagingBinding.ProxyAddress | string, optional (see note) | Twilio Brand phone number used by participant |
| MessagingBinding.Address | string, optional (see note) | Originating phone number of the participant |
| MessagingBinding.Type | 文字列 | Type of the participant, one of: SMS, CHAT, WHATSAPP |
Note: Participant has either the Identity or MessagingBinding.ProxyAddress and MessagingBinding.Address attributes supplied. If the added participant is Chat-only, the Identity value is provided, and both MessagingBinding addresses are null.
onDeliveryUpdated
| パラメーター名 | タイプ | description |
|---|---|---|
| EventType | 文字列 | onDeliveryUpdated |
| AccountSid | string, SID | SID of the account that the message belongs to, ACxx |
| ConversationSid | string, SID | Conversation String Identifier, CHxx |
| ChatServiceSid | string, SID | Chat Service instance SID, ISxx |
| Message SID | string, SID | Identifier of Conversation Message, IMxxx |
| DeliveryReceiptSid | string, SID | SID of the Delivery Receipt, DYxx |
| ChannelMessageSid | string, SID | SID of the ‘channel’ message e.g WAxx for WhatsApp, SMxx for SMS |
| ParticipantSid | string, SID | Participant String Identifier, MBxx |
| Status | string, enum | Status of the message, one of "read", "failed", "delivered", "undelivered", "sent" |
| ErrorCode | integer | Twilio documented numeric error code |
| DateCreated | string, ISO8601 time | Date delivery receipt was created |
| DateUpdated | string, ISO8601 time | Date that delivery receipt was last created |
ヘルプが必要ですか？
誰しもが一度は考える「コーディングって難しい」。そんな時は、お問い合わせフォームから質問してください。 または、Stack Overflow でTwilioタグのついた情報から欲しいものを探してみましょう。