Webhook Events

Programmable Chat event callbacks allow you to monitor and intercept specific events in your backend service. The two categories of events are "Pre-Event" (synchronous) and "Post-Event" (asynchronous). When a callback is specified Twilio will make an HTTP request to the designated webhook URL. This request contains all relevant variable data.

"Pre-Event" Webhooks allow you to decide whether to allow, modify or disallow the action. In these types of events, the request from Twilio does not include the resource SID to allow for pre-creation events as the SID will not yet exist. These event callbacks are blocking/synchronous calls, which means that Chat will wait for a response (or timeout) before processing the operation.

"Post-Event" webhooks are "notify only" and provide information after the action has completed. These events require no response, but non-200 OK responses are logged as errors for information purposes. These event callbacks include all the relevant variable data, include the resource SID for create operations. These are not blocking callbacks as they are informational.

Event callbacks are configured per Service instance - and can be different per instance.

Note: Only commands and events triggered from SDK client endpoints will trigger the event callback (if configured). REST API actions will currently not trigger these.

Table of Contents

Pre-Event Callbacks

Event fired Action that triggered
onMessageSend Send Message
onMessageRemove Remove/Delete a Message
onMessageUpdate Edit a Message
onChannelAdd Create Channel
onChannelUpdate Edit Channel FriendlyName or Attributes
onChannelDestroy Delete/Destroy Channel
onMemberAdd Channel Member Join or Add
onMemberRemove Channel Member Remove or Leave
onUserUpdate A property of a User is being updated. Note this PRE event will not be fired in response to a Reachability state change for the User

Pre-Event processing callbacks from your server

  1. Process the callback POST
  2. Determine if the action that triggered the callback should be allowed
  3. If yes, return an HTTP 200 OK response - this tells the Chat service to continue processing
  4. If yes, but you wish to modify some part of the entity the action relates to, return the modification details in a JSON response body
  5. If no, return an HTTP 403 FORBIDDEN response - this tells the Chat service to not continue and fail the operation

Note: If an event callback is configured but the URL specified returns a 404 NOT FOUND response, Chat will continue processing the action as normal.

Post-Event Callbacks

Event fired Action that triggered
onMessageSent Message sent
onMessageRemoved Message removed/deleted
onMessageUpdated Message edited
onChannelAdded Channel created
onChannelUpdated Channel FriendlyName or Attributes updated
onChannelDestroyed Channel Deleted/Destroyed
onMemberAdded Channel Member Joined or Added
onMemberRemoved Channel Member Removed or Left
onUserUpdated A User attribute or property was updated or changed. This POST event will fire in response to a Reachability state change for the User.

Configuring callback webhooks

Chat WebHooks are configured per Service instance. The top level configuration items are:

attribute name type required description
PreWebhookUrl string required The absolute URL where the callback should make an HTTP request for PRE events
PostWebhookUrl string required The absolute URL where the callback should make an HTTP request for POST events
WebhookMethod string required The method for issuing the HTTP request - this can be GET or POST
WebhookFilters string required List of Webhooks to enable for this Service instance. The entire list must always be sent.
Loading Code Samples...
Language
curl -X POST https://chat.twilio.com/v1/Services/{service sid} \
-d 'PreWebhookUrl=https://hooks.yoursite.com/pre-webhooks' \
-d 'PostWebhookUrl=https://hooks.yoursite.com/post-webhooks' \
-d 'WebhookMethod=POST' \
-u '{twilio account sid}:{twilio auth token}'
Configure the top-level WebHook settings for a Service instance (excluding the actual events)
Chat Service Instance WebHook settings

Configure the top-level WebHook settings for a Service instance (excluding the actual events)

To remove a Webhook, omit the relevant Webhook from the WebhookFilters request parameter list, and it will be removed/disabled.

The WebhookFilters parameter should be passed in the standard request format, with multiple values passed as individual request parameters for the same name.

Loading Code Samples...
Language
curl -X POST https://chat.twilio.com/v1/Services/{service sid} \
-d 'WebhookFilters=onMessageSend' \
-d 'WebhookFilters=onMessageSent' \
-d 'WebhookFilters=onMessageUpdate' \
-d 'WebhookFilters=onMessageUpdated' \
-d 'WebhookFilters=onMessageRemove' \
-d 'WebhookFilters=onMessageRemoved' \
-d 'WebhookFilters=onChannelAdd' \
-d 'WebhookFilters=onChannelAdded' \
-d 'WebhookFilters=onChannelDestroy' \
-d 'WebhookFilters=onChannelDestroyed' \
-d 'WebhookFilters=onChannelUpdate' \ 
-d 'WebhookFilters=onChannelUpdated' \ 
-d 'WebhookFilters=onMemberAdd' \ 
-d 'WebhookFilters=onMemberAdded' \ 
-d 'WebhookFilters=onMemberRemove' \ 
-d 'WebhookFilters=onMemberRemoved' \ 
-d 'WebhookFilters=onUserUpdate' \
-d 'WebhookFilters=onUserUpdated' \
-u '{twilio account sid}:{twilio auth token}'

Enable all the available PRE and POST event callbacks for a Service instance
Enable all Event Callbacks via Chat Webhooks

Enable all the available PRE and POST event callbacks for a Service instance

Webhook request parameters

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:

parameter name type 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
Identity string 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 events request parameters

OnMessageSend
parameter name type description
EventType string Always onMessageSend
ChannelSid string Channel SID identifier of the Channel the Message is being sent to
Body string The body of message
Attributes 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 string The author of the message
DateCreated date string The timestamp of creation of the message (DEPRECATED)
To string Channel String Identifier of the Channel the Message is being sent to (DEPRECATED)
OnMessageRemove
parameter name type description
EventType string Always onMessageRemove
MessageSid string The Message SID
ChannelSid string SID identifier of the Channel the Message is being sent to
Body string The body of message
Attributes string, optional, valid JSON structure or null Stringified JSON structure. This can be null if attributes are not present in message entity.
From string The author of the message
DateCreated date string The timestamp from message creation
RemovedBy string The remover of the message
To string Channel String Identifier of the Channel the Message is being sent to (DEPRECATED)
OnMessageUpdate
parameter name type description
EventType string Always onMessageUpdate
MessageSid string The Message SID
ChannelSid string SID identifier of the Channel the Message is being sent to
Body string The body of message
Attributes string, optional, valid JSON structure or null Stringified JSON structure. This can be null if attributes are not present in message entity
From string The author of the message
DateCreated date string The timestamp from message creation
ModifiedBy string The updater/modifier of the message
To string Channel String Identifier of the Channel the Message is being sent to (DEPRECATED)
OnChannelAdd
parameter name type description
EventType string Always onChannelAdd
Attributes string, optional, valid JSON structure or null Stringified JSON structure. This can be null if attributes are not present in channel entity
CreatedBy string The identity of the user that created a channel
FriendlyName string, optional The friendly name of the channel, if set
UniqueName string, optional The unique name of the channel, if set
ChannelType string The Channel type. Either private or public
DateCreated date string The date of creation of the channel (DEPRECATED)
Name string, optional The friendly name of the channel, if set (DEPRECATED)
ChannelSid string Channel String Identifier (DEPRECATED)
OnChannelDestroy
parameter name type description
EventType string Always onChannelDestroy
ChannelSid string Channel String Identifier
Attributes string, optional, valid JSON structure or null Stringified JSON structure. This can be null if attributes are not present in channel entity
DateCreated string The date of creation of the channel
CreatedBy date string The identity of the user that created a channel
FriendlyName string, optional The friendly name of the channel, if set
UniqueName string, optional The unique name of the channel, if set
ChannelType string The Channel type. Either private or public
Name string, optional The friendly name of the channel, if set (DEPRECATED)
OnChannelUpdate
parameter name type description
EventType string Always onChannelUpdate
ChannelSid string Channel String Identifier
Attributes 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, The date of creation of the channel
CreatedBy string The identity of the user that created a channel
FriendlyName string, optional The friendly name of the channel, if set
UniqueName string, optional The unique name of the channel, if set
Name string, optional The friendly name of the channel, if set (DEPRECATED)
OnMemberAdd
parameter name type description
EventType string Always onMemberAdd
ChannelSid string Channel String Identifier
Identity string The Identity of the User being added to the channel as a Member
RoleSid string, optional The Role SID of added member
Reason string The reason for the addition of the member. Could be: ADDED or JOINED
Role string, optional The role of added member (DEPRECATED)
OnMemberRemove
parameter name type description
EventType string Always onMemberRemove
ChannelSid string Channel String Identifier
Identity string The Identity of the User being removed from the channel
MemberSid string The member SID of member being removed
RoleSid string, optional The role of removed member
Reason string The reason of the removal of the member. Could be: REMOVED or LEFT
Role string, optional The role of removed member (DEPRECATED)
OnUserUpdate
parameter name type description
UserSid string, SID The SID of the User about to be updated
EventType string Always onUserUpdate
Identity string The Identity of the User being updated
FriendlyName string, optional The optional (if set) FriendlyName of the User being updated
RoleSid string 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
Attributes 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
parameter name type description
EventType string Always onMessageSent
MessageSid string The Message SID of the new Message
Index int The index of the Message within the Channel Message list
ChannelSid string Channel SID identifier of the Channel the Message is being sent to
Body string The body of the message
Attributes string, optional, valid JSON structure or null Stringified JSON structure. This can be null if attributes are not present in message entity
From string The author of the message
DateCreated date string The timestamp of message creation
OnMessageRemoved
parameter name type description
EventType string Always onMessageRemoved
MessageSid string The Message SID of the removed Message
Index int The index of the removed Message within the Channel Message list
ChannelSid string The SID identifier of the Channel the Message is being sent to
Body string The body of message
Attributes string, optional, valid JSON structure or null Stringified JSON structure. This can be null if attributes are not present in message entity
From string The author of the message
RemovedBy string The remover of the message
DateCreated date string The timestamp of message creation
DateRemoved date string The timestamp of removal of the message
OnMessageUpdated
parameter name type description
EventType string Always onMessageUpdated
MessageSid string The Message SID of the updated Message
Index int The index of the updated Message within the Channel Message list
ChannelSid string SID identifier of the Channel the Message is being sent to
Body string The body of message
Attributes string, optional, valid JSON structure or null Stringified JSON structure. This can be null if attributes are not present in message entity
From string The author of the message
ModifiedBy string The identity of the user that updated the message
DateCreated date string The timestamp of message creation
DateUpdated date string The timestamp of update of the message
OnChannelAdded
parameter name type description
EventType string Always onChannelAdded
ChannelSid string The SID of the newly added Channel
Attributes string, optional, JSON structure The arbitrary JSON structure of the channel
DateCreated date string The date of channel creation
CreatedBy string The identity of the user that created a channel
FriendlyName string, optional The friendly name of the channel, if set
UniqueName string, optional The unique name of the channel, if set
ChannelType string The Channel type. Either private or public
OnChannelDestroyed
parameter name type description
EventType string Always onChannelDestroyed
ChannelSid string Channel String Identifier
Attributes string, optional, JSON structure The arbitrary JSON structure of the channel
DateCreated date string, The date of creation of the channel
DateDestroyed date string, The date of destruction of the channel
CreatedBy string The identity of the user that created a channel
FriendlyName string, optional The friendly name of the channel, if set
UniqueName string, optional The unique name of the channel, if set
ChannelType string The Channel type. Either private or public
OnChannelUpdated
parameter name type description
EventType string Always onChannelUpdated
ChannelSid string Channel String Identifier
Attributes string, optional, JSON structure The arbitrary JSON structure of the channel
DateCreated date string, The date of creation of the channel
DateUpdated date string The date of update of the channel
CreatedBy string The identity of the user that created a channel
FriendlyName string, optional The friendly name of the channel, if set
UniqueName string, optional The unique name of the channel, if set
ChannelType string The Channel type. Either private or public
OnMemberAdded
parameter name type description
EventType string Always onMemberAdded
MemberSid string The Member SID of the newly added Member
ChannelSid string Channel String Identifier
Identity string The Identity of the User being added to the channel as a Member
RoleSid string, optional The Role SID of added member
Reason string The reason for the addition of the member. Could be ADDED or JOINED
DateCreated date string The date of Member addition
OnMemberRemoved
parameter name type description
EventType string Always onMemberRemoved
ChannelSid string Channel String Identifier
Identity string The Identity of the User being removed from the channel
MemberSid string The Member SID of member being removed
RoleSid string, optional The role of removed member
Reason string The reason for the removal of the member. Could be REMOVED or LEFT
DateCreated date string The date of Member addition
DateRemoved date string The date of Member removal
OnUserUpdated
parameter name type description
UserSid string, SID The SID of the User that was updated.
EventType string Always onUserUpdated
Identity string The Identity of the User that was updated
FriendlyName string, optional The optional FriendlyName (if set) of the updated User
RoleSid string 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
Attributes 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.

Synchronous action modification in response

For synchronous (PRE event) webhook calls, you can respond with a JSON body to modify the action. For example, to change message body, you can send the following JSON as the response body:

{
    "body" : "modified message body" 
}

All values are optional, and missing fields won’t be replaced with null. To provide a null value, you must set the field to JSON.NULL in the response.

All values must be validated. If validation fails, then Chat will send an error code to the client that initiated the action.

You can modify any attribute related to the event entity. For example, when an onChannelUpdate WebHook is triggered for the editChannelFriendlyName command, you can choose to also modify the UniqueName of the Channel as part of the same action.

Modifications made using this method are only valid for PRE event (synchronous) WebHook calls and create and update events (i.e. not for deletes).

Note: The parameter/field variable names in the JSON response must be in the snake_case format.

Valid events and entity fields available for in-response action modification are listed below:

Channel

Applicable event types

  • OnChannelAdd
  • OnChannelUpdate

Updatable fields

  • FriendlyName
  • UniqueName
  • Attributes

Example response body JSON

    "friendly_name": "friendly name of channel",
    "unique_name": "very unique name",
    "attributes" : "{\"key\" : \"value\"}"
}

Message

Applicable event types

  • OnMessageSend
  • OnMessageUpdate

Updatable fields

  • Body
  • From
  • Attributes

Example JSON

    "body": "modified message text",
    "from": "modified from value",
    "attributes" : "{\"key\" : \"value\"}"
}

User

Applicable event types

  • OnUserUpdate

Updatable fields

  • FriendlyName
  • Attributes

Example JSON

{
    "friendly_name": "modified friendly name",
    "attributes": "{\"key\" : \"value\"}"
}

Error Handling

If the webhook client throws any exception, this error gets logged, and the result of webhook is considered Continue.

Need some help?

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.

1 / 1
Loading Code Samples...
curl -X POST https://chat.twilio.com/v1/Services/{service sid} \
-d 'PreWebhookUrl=https://hooks.yoursite.com/pre-webhooks' \
-d 'PostWebhookUrl=https://hooks.yoursite.com/post-webhooks' \
-d 'WebhookMethod=POST' \
-u '{twilio account sid}:{twilio auth token}'
curl -X POST https://chat.twilio.com/v1/Services/{service sid} \
-d 'WebhookFilters=onMessageSend' \
-d 'WebhookFilters=onMessageSent' \
-d 'WebhookFilters=onMessageUpdate' \
-d 'WebhookFilters=onMessageUpdated' \
-d 'WebhookFilters=onMessageRemove' \
-d 'WebhookFilters=onMessageRemoved' \
-d 'WebhookFilters=onChannelAdd' \
-d 'WebhookFilters=onChannelAdded' \
-d 'WebhookFilters=onChannelDestroy' \
-d 'WebhookFilters=onChannelDestroyed' \
-d 'WebhookFilters=onChannelUpdate' \ 
-d 'WebhookFilters=onChannelUpdated' \ 
-d 'WebhookFilters=onMemberAdd' \ 
-d 'WebhookFilters=onMemberAdded' \ 
-d 'WebhookFilters=onMemberRemove' \ 
-d 'WebhookFilters=onMemberRemoved' \ 
-d 'WebhookFilters=onUserUpdate' \
-d 'WebhookFilters=onUserUpdated' \
-u '{twilio account sid}:{twilio auth token}'