Webhookイベント
Programmable Chat sends webhooks for most things that happen in your app, and are designed to allow you to monitor and intercept user actions in your own backend service, in a Function, or in a Studio flow.
Webhook targets for the Service instance (the URL that Twilio will invoke) are configured in the Twilio Console. Twilio will fire these webhooks at two different moments:
- Pre-Event Webhooks will fire before an action has been committed to the Chat instance, blocking publication until a response is received. This gives your backend (or Function) the opportunity to intercept, modify, or reject any action across the instance, making these hooks useful for spam/language filtering, complex permission schemes, or other business logic. Pre-event webhooks are fired only for actions from the Chat SDK; the REST API actions will never fire them.
- Post-Event Webhooks fire after any action taken on a Chat Service. This means they arrive after messages have been delivered, after channel membership has changed, etc. Post-Event hooks are therefore the right tool for archiving or post-processing. Unlike Pre-Event webhooks, Post-Event webhooks can also be triggered from the REST API if the correct header is passed (see below).
Additionally to global, service-level webhooks, Channel-Scoped Webhooks allow you to configure up to five specific webhooks per channel, optionally triggering them on specific words or phrases.
During Beta, Media Messages do not trigger any webhooks, pre-event or post-event.
Webhook Event Triggers
Most events — but not all of them — have both a pre-event and a post-event webhook. The former is fired before the event has been published, and Twilio waits for a response before publishing it. The latter are fired after publication, assuming the event was not rejected by your pre-event webhook response.
The below table enumerates all Chat webhook events in corresponding pairs.
Pre-Event | Post-Event | Description (incl. Post-Event) |
onMessageSend |
onMessageSent |
Fires when a new message is posted to a channel. |
onMessageRemove |
onMessageRemoved |
Fires when a message is deleted from a channel. |
onMessageUpdate |
onMessageUpdated |
Fires when a posted message's body or any attribute is changed. |
onMediaMessageSend |
onMediaMessageSent |
Fires when a new media message is posted to a channel. |
onChannelAdd |
onChannelAdded |
Fires when a new channel, public or private, is created. |
onChannelUpdate |
onChannelUpdated |
Fires when any attribute of a channel is changed. |
onChannelDestroy |
onChannelDestroyed |
Fires when a channel is removed from the Service. |
onMemberAdd |
onMemberAdded |
Fires when a User has joined a Channel as a Member. |
onMemberRemove |
onMemberRemoved |
Fires when a User is removed from the set of Channel Members. |
(no pre-event webhook) |
onUserAdded |
Fires when a new User has been created. (cannot be intercepted with a Pre-Event hook) |
onUserUpdate |
onUserUpdated |
Fires when any configurable attribute of a User is changed. Will not be fired for reachability events. |
Triggering Webhooks for REST API Events
Upon configuration, only actions from SDK-driven clients (like mobile phones or browsers) will cause webhooks without further action on your part. This includes both Service-level webhooks and Channel-Scoped Webhooks, and as a default behavior helps 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.
Headers are not currently supported by the Twilio REST Helper Libraries. If you want to enable webhooks from REST, you will need to construct Twilio REST requests in a native HTTP library.
Using Pre-Event Webhooks to Modify or Reject Changes
In the case of Pre-Event 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 Programmable Chat will proceed.
Response Status Code | Body | Result |
HTTP 200 OK | {} (or no content) |
Chat will publish the change unmodified. |
HTTP 200 OK |
|
Chat 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 (Channels, Messages, or Users). If modified values fail validation, the error will be returned to the SDK (or REST client) that triggered the event. |
HTTP 403 Forbidden | (なし) | Chat will reject the change and no publication will be made. |
HTTP 404 Not Found | (なし) | Chat will publish the change unmodified. |
(no response or timeout) | Chat will publish the change unmodified. |
Modifiable Fields
In all cases, any change to the attributes
value will be applied wholly; you cannot partially-update this value by providing only a subset of fields. The new value for attributes, as ever, must be provided as a string with all intervening double-quotes escaped.
Channel Events
In response to the onChannelAdd and onChannelUpdate events, your Pre-Event Webhook response may modify the following properties of the channel:
friendly_name
unique_name
attributes
An example response modifying a channel
HTTP 200 OK
Content-Type: text/json
{
"friendly_name": "friendly name of channel",
"unique_name": "very unique name",
"attributes" : "{\"key\" : \"value\"}"
}
Message Events
In response to onMessageSend and onMessageUpdate events, your Pre-Event Webhook response may modify the following properties of the message:
body
attributes
An example response modifying a chat message.
HTTP 200 OK
Content-Type: text/json
{
"body": "modified message text",
"attributes": "{\"key\" : \"value\"}"
}
User Events
In response to onUserUpdate events, your Pre-Event Webhook response may modify the following properties of the User:
friendly_name
attributes
An example response modifying a chat User.
HTTP 200 OK
Content-Type: text/json
{
"friendly_name": "modified friendly name",
"attributes": "{\"key\" : \"value\"}"
}
Configuring Webhooks with the REST API
Service-level Webhooks, both Pre-Event and Post-Event, are configured on the Service itself with the following parameters.
Configuration Attribute | Type | Meaning |
PreWebhookUrl |
string (absolute url) | The absolute URL where Twilio should send Pre-Event webhook requests. |
PostWebhookUrl |
string (absolute url) | The absolute URL where Twilio should send Post-Event webhook requests. |
WebhookMethod |
string ("POST" or "GET") | Twilio will use this HTTP method when sending webhook requests of all types. |
WebhookFilters |
string, repeatable | The list of webhook event triggers that are enabled for this Service. The entire list must be provided on any POST to Service configuration. |
PreWebhookRetryCount |
integer [0, 3] | Pre-Event webhooks that fail after a 5s timeout will be retried according to this setting. The maximum number of retries is 3 (i.e. 4 attempts total). |
PostWebhookRetryCount |
integer [0, 3] | Post-Event webhooks that fail after a 5s timeout will be retried according to this setting. The maximum number of retries is 3 (i.e. 4 attempts total). |
Webhook Bodies by Event Type
When Twilio makes an HTTP request to your server, it will include contextual information related to the action that triggered the WebHook call to your backend.
In addition to the event-specific parameters, each request will also contain the following parameters and information:
パラメーター名 | タイプ | description |
---|---|---|
AccountSid | string, SID | The Twilio Account SID which the Service instance belongs to |
InstanceSid | string, sid | The Programmable Chat Service instance SID which the action relates to |
ClientIdentity | 文字列 | The identity string of the SDK client endpoint that triggered the event callback (as taken from the Access Token for the client endpoint). |
Note: Each HTTP request is issued with the Content-Type
header application/x-www-urlencoded
.
Pre-Event Webhook Bodies
OnMessageSend
パラメーター名 | タイプ | description |
---|---|---|
EventType | 文字列 | Always onMessageSend |
Channel SID | 文字列 | このメッセージの送信先 チャンネルのチャンネル SID ID |
Body | 文字列 | メッセージの本文 |
属性 | string, optional, valid JSON structure or null | A JSON structure contained in a string. This can be null if attributes are not present in message entity. |
From | 文字列 | メッセージの作成者 |
DateCreated | 日付文字列 | メッセージの作成日 (廃止予定) |
To | 文字列 | このメッセージの送信先チャンネルのチャンネル文字列識別子 (廃止予定) |
OnMessageRemove
パラメーター名 | タイプ | description |
---|---|---|
EventType | 文字列 | Always onMessageRemove |
Message SID | 文字列 | メッセージ SID |
Channel SID | 文字列 | SID identifier of the Channel the Message is being sent to |
Body | 文字列 | メッセージの本文 |
属性 | string, optional, valid JSON structure or null | Stringified JSON structure. This can be null if attributes are not present in message entity. |
From | 文字列 | メッセージの作成者 |
DateCreated | 日付文字列 | The timestamp from message creation |
RemovedBy | 文字列 | メッセージの削除者 |
To | 文字列 | このメッセージの送信先チャンネルのチャンネル文字列識別子 (廃止予定) |
OnMessageUpdate
パラメーター名 | タイプ | description |
---|---|---|
EventType | 文字列 | Always onMessageUpdate |
Message SID | 文字列 | メッセージ SID |
Channel SID | 文字列 | SID identifier of the Channel the Message is being sent to |
Body | 文字列 | メッセージの本文 |
属性 | string, optional, valid JSON structure or null | Stringified JSON structure. This can be null if attributes are not present in message entity |
From | 文字列 | メッセージの作成者 |
DateCreated | 日付文字列 | The timestamp from message creation |
ModifiedBy | 文字列 | メッセージの更新者/修正者 |
To | 文字列 | このメッセージの送信先チャンネルのチャンネル文字列識別子 (廃止予定) |
OnMediaMessageSend
パラメーター名 | タイプ | description |
---|---|---|
EventType | 文字列 | Always onMessageSend |
Channel SID | 文字列 | このメッセージの送信先 チャンネルのチャンネル SID ID |
Body | 文字列 | メッセージの本文 |
属性 | string, optional, valid JSON structure or null | A JSON structure contained in a string. This can be null if attributes are not present in message entity. |
From | 文字列 | メッセージの作成者 |
MediaFilename | 文字列 | The filename of the underlying media file as specified when uploaded |
MediaContentType | 文字列 | The MIME type of the file this media represents. |
MediaSid | 文字列 | Media SID identifier |
MediaSize | int | Media size in bytes |
DateCreated | 日付文字列 | メッセージの作成日 (廃止予定) |
To | 文字列 | このメッセージの送信先チャンネルのチャンネル文字列識別子 (廃止予定) |
OnChannelAdd
パラメーター名 | タイプ | description |
---|---|---|
EventType | 文字列 | Always onChannelAdd |
属性 | string, optional, valid JSON structure or null | Stringified JSON structure. This can be null if attributes are not present in channel entity |
CreatedBy | 文字列 | チャンネルを作成したユーザーのアイデンティティ |
FriendlyName | 文字列、オプション | チャンネルのフレンドリーネーム(設定されている場合) |
UniqueName | 文字列、オプション | チャンネルの一意の名前(設定されている場合) |
ChannelType | 文字列 | The Channel type. Either private or public |
DateCreated | 日付文字列 | チャンネルの作成日 (廃止予定) |
名前 | 文字列、オプション | チャンネルのフレンドリーネーム(設定されている場合) (廃止予定) |
Channel SID | 文字列 | チャンネルの文字列識別子 (廃止予定) |
OnChannelDestroy
パラメーター名 | タイプ | description |
---|---|---|
EventType | 文字列 | Always onChannelDestroy |
Channel SID | 文字列 | チャンネルの文字列識別子 |
属性 | string, optional, valid JSON structure or null | Stringified JSON structure. This can be null if attributes are not present in channel entity |
DateCreated | 文字列 | チャンネルの作成日 |
CreatedBy | 日付文字列 | チャンネルを作成したユーザーのアイデンティティ |
FriendlyName | 文字列、オプション | チャンネルのフレンドリーネーム(設定されている場合) |
UniqueName | 文字列、オプション | チャンネルの一意の名前(設定されている場合) |
ChannelType | 文字列 | The Channel type. Either private or public |
名前 | 文字列、オプション | チャンネルのフレンドリーネーム(設定されている場合) (廃止予定) |
OnChannelUpdate
パラメーター名 | タイプ | description |
---|---|---|
EventType | 文字列 | Always onChannelUpdate |
Channel SID | 文字列 | チャンネルの文字列識別子 |
属性 | string, optional, valid JSON structure or null | Stringified JSON structure. This can be null if attributes are not present in channel entity. |
DateCreated | date string, | チャンネルの作成日 |
CreatedBy | 文字列 | チャンネルを作成したユーザーのアイデンティティ |
FriendlyName | 文字列、オプション | チャンネルのフレンドリーネーム(設定されている場合) |
UniqueName | 文字列、オプション | チャンネルの一意の名前(設定されている場合) |
名前 | 文字列、オプション | チャンネルのフレンドリーネーム(設定されている場合) (廃止予定) |
OnMemberAdd
パラメーター名 | タイプ | description |
---|---|---|
EventType | 文字列 | Always onMemberAdd |
Channel SID | 文字列 | チャンネルの文字列識別子 |
Identity | 文字列 | The Identity of the User being added to the channel as a Member |
roleSid | 文字列、オプション | 追加したメンバーのロール SID |
reason | 文字列 | The reason for the addition of the member. Could be: ADDED or JOINED |
ロール | 文字列、オプション | 追加されるメンバーのロール (廃止予定) |
OnMemberRemove
パラメーター名 | タイプ | description |
---|---|---|
EventType | 文字列 | Always onMemberRemove |
Channel SID | 文字列 | チャンネルの文字列識別子 |
Identity | 文字列 | The Identity of the User being removed from the channel |
MemberSid | 文字列 | 削除されるメンバーのメンバー SID |
roleSid | 文字列、オプション | 削除されるメンバーのロール |
reason | 文字列 | The reason of the removal of the member. Could be: REMOVED or LEFT |
ロール | 文字列、オプション | 削除されるメンバーのロール (廃止予定) |
OnUserUpdate
パラメーター名 | タイプ | description |
---|---|---|
UserSid | string, SID | The SID of the User about to be updated |
EventType | 文字列 | Always onUserUpdate |
Identity | 文字列 | The Identity of the User being updated |
FriendlyName | 文字列、オプション | The optional (if set) FriendlyName of the User being updated |
roleSid | 文字列 | The Role SID the user being updated |
DateCreated | string, ISO8601 time | The date and time of initial User creation |
DateUpdated | string, ISO8601 time | The date and time the user was last updated |
属性 | JSON, string, optional | The optional Attributes (if set) of the User being updated as a JSON structure in string format. |
IsOnline | boolean, optional | true if the user has an active session and can create and receive real-time events. This field is present only if the Reachability Indicator feature is enabled for the Service instance. |
IsNotifiable | boolean, optional | true if the user has an active session and can create and receive push notifications. This field is present only if the Reachability Indicator and Push Notifications features are enabled for the Service instance. The User must have at least one Push Notification registration for Chat. |
POST events request parameters
OnMessageSent
パラメーター名 | タイプ | description |
---|---|---|
EventType | 文字列 | Always onMessageSent |
Message SID | 文字列 | The Message SID of the new Message |
index | int | The index of the Message within the Channel Message list |
Channel SID | 文字列 | このメッセージの送信先 チャンネルのチャンネル SID ID |
Body | 文字列 | The body of the message |
属性 | string, optional, valid JSON structure or null | Stringified JSON structure. This can be null if attributes are not present in message entity |
From | 文字列 | メッセージの作成者 |
DateCreated | 日付文字列 | The timestamp of message creation |
OnMessageRemoved
パラメーター名 | タイプ | description |
---|---|---|
EventType | 文字列 | Always onMessageRemoved |
Message SID | 文字列 | The Message SID of the removed Message |
index | int | The index of the removed Message within the Channel Message list |
Channel SID | 文字列 | The SID identifier of the Channel the Message is being sent to |
Body | 文字列 | メッセージの本文 |
属性 | string, optional, valid JSON structure or null | Stringified JSON structure. This can be null if attributes are not present in message entity |
From | 文字列 | メッセージの作成者 |
RemovedBy | 文字列 | メッセージの削除者 |
DateCreated | 日付文字列 | The timestamp of message creation |
DateRemoved | 日付文字列 | The timestamp of removal of the message |
OnMessageUpdated
パラメーター名 | タイプ | description |
---|---|---|
EventType | 文字列 | Always onMessageUpdated |
Message SID | 文字列 | The Message SID of the updated Message |
index | int | The index of the updated Message within the Channel Message list |
Channel SID | 文字列 | SID identifier of the Channel the Message is being sent to |
Body | 文字列 | メッセージの本文 |
属性 | string, optional, valid JSON structure or null | Stringified JSON structure. This can be null if attributes are not present in message entity |
From | 文字列 | メッセージの作成者 |
ModifiedBy | 文字列 | The identity of the user that updated the message |
DateCreated | 日付文字列 | The timestamp of message creation |
DateUpdated | 日付文字列 | The timestamp of update of the message |
OnMediaMessageSent
パラメーター名 | タイプ | description |
---|---|---|
EventType | 文字列 | Always onMessageSent |
Message SID | 文字列 | The Message SID of the new Message |
index | int | The index of the Message within the Channel Message list |
Channel SID | 文字列 | このメッセージの送信先 チャンネルのチャンネル SID ID |
Body | 文字列 | The body of the message |
属性 | string, optional, valid JSON structure or null | Stringified JSON structure. This can be null if attributes are not present in message entity |
From | 文字列 | メッセージの作成者 |
DateCreated | 日付文字列 | The timestamp of message creation |
MediaFilename | 文字列 | The filename of the underlying media file as specified when uploaded |
MediaContentType | 文字列 | The MIME type of the file this media represents. |
MediaSid | 文字列 | Media SID identifier |
MediaSize | int | Media size in bytes |
OnChannelAdded
パラメーター名 | タイプ | description |
---|---|---|
EventType | 文字列 | Always onChannelAdded |
Channel SID | 文字列 | The SID of the newly added Channel |
属性 | 文字列、オプション、JSON 構造 | チャンネルの任意の JSON 構造 |
DateCreated | 日付文字列 | The date of channel creation |
CreatedBy | 文字列 | チャンネルを作成したユーザーのアイデンティティ |
FriendlyName | 文字列、オプション | チャンネルのフレンドリーネーム(設定されている場合) |
UniqueName | 文字列、オプション | チャンネルの一意の名前(設定されている場合) |
ChannelType | 文字列 | The Channel type. Either private or public |
OnChannelDestroyed
パラメーター名 | タイプ | description |
---|---|---|
EventType | 文字列 | Always onChannelDestroyed |
Channel SID | 文字列 | チャンネルの文字列識別子 |
属性 | 文字列、オプション、JSON 構造 | チャンネルの任意の JSON 構造 |
DateCreated | date string, | チャンネルの作成日 |
DateDestroyed | date string, | The date of destruction of the channel |
CreatedBy | 文字列 | チャンネルを作成したユーザーのアイデンティティ |
FriendlyName | 文字列、オプション | チャンネルのフレンドリーネーム(設定されている場合) |
UniqueName | 文字列、オプション | チャンネルの一意の名前(設定されている場合) |
ChannelType | 文字列 | The Channel type. Either private or public |
OnChannelUpdated
パラメーター名 | タイプ | description |
---|---|---|
EventType | 文字列 | Always onChannelUpdated |
Channel SID | 文字列 | チャンネルの文字列識別子 |
属性 | 文字列、オプション、JSON 構造 | チャンネルの任意の JSON 構造 |
DateCreated | date string, | チャンネルの作成日 |
DateUpdated | 日付文字列 | The date of update of the channel |
CreatedBy | 文字列 | チャンネルを作成したユーザーのアイデンティティ |
FriendlyName | 文字列、オプション | チャンネルのフレンドリーネーム(設定されている場合) |
UniqueName | 文字列、オプション | チャンネルの一意の名前(設定されている場合) |
ChannelType | 文字列 | The Channel type. Either private or public |
OnMemberAdded
パラメーター名 | タイプ | description |
---|---|---|
EventType | 文字列 | Always onMemberAdded |
MemberSid | 文字列 | The Member SID of the newly added Member |
Channel SID | 文字列 | チャンネルの文字列識別子 |
Identity | 文字列 | The Identity of the User being added to the channel as a Member |
roleSid | 文字列、オプション | 追加したメンバーのロール SID |
reason | 文字列 | The reason for the addition of the member. Could be ADDED or JOINED |
DateCreated | 日付文字列 | The date of Member addition |
OnMemberRemoved
パラメーター名 | タイプ | description |
---|---|---|
EventType | 文字列 | Always onMemberRemoved |
Channel SID | 文字列 | チャンネルの文字列識別子 |
Identity | 文字列 | The Identity of the User being removed from the channel |
MemberSid | 文字列 | 削除されるメンバーのメンバー SID |
roleSid | 文字列、オプション | 削除されるメンバーのロール |
reason | 文字列 | The reason for the removal of the member. Could be REMOVED or LEFT |
DateCreated | 日付文字列 | The date of Member addition |
DateRemoved | 日付文字列 | The date of Member removal |
OnUserUpdated
パラメーター名 | タイプ | description |
---|---|---|
UserSid | string, SID | The SID of the User that was updated. |
EventType | 文字列 | Always onUserUpdated |
Identity | 文字列 | The Identity of the User that was updated |
FriendlyName | 文字列、オプション | The optional FriendlyName (if set) of the updated User |
roleSid | 文字列 | The Role SID the User that was updated |
DateCreated | string, ISO8601 time | The date and time the User was first created |
DateUpdated | string, ISO8601 time | The date and time the User was updated |
属性 | JSON, string, optional | The optional Attributes of the updated user (if set). JSON structure in string format. |
IsOnline | boolean, optional | true if the user has an active session and can create and receive real-time events. This field is present only if Reachability Indicator feature is enabled for the Service instance. |
IsNotifiable | boolean, optional | true if the user has an active session and can create and receive push notifications. This field is present only if the Reachability Indicator and Push Notifications features are enabled for the Service instance. The User must also have at least one Push Notification registration for Chat. |
OnUserAdded
パラメーター名 | タイプ | description |
---|---|---|
UserSid | string, SID | The SID of the User that was updated. |
EventType | 文字列 | Always onUserAdded |
Identity | 文字列 | The Identity of the User that was updated |
FriendlyName | 文字列、オプション | The optional FriendlyName (if set) of the updated User |
roleSid | 文字列 | The Role SID the User that was updated |
DateCreated | string, ISO8601 time | The date and time the User was first created |
属性 | JSON, string, optional | The optional Attributes of the updated user (if set). JSON structure in string format. |
ヘルプが必要ですか?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.