Menu

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Webhook Events

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.

The Webhooks configuration page is accessible from the left nav bar when configuring a Chat service.

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.
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

{ "body": "modified message" }

(See the list of modifiable fields.)

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 (none) Chat will reject the change and no publication will be made.
HTTP 404 Not Found (none) 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).
Loading Code Sample...
      
      
      
      
      This snippet configures the URLs invoked by Twilio. It does not change the set of enabled webhook event triggers.

      Configuring Chat Webhook URLs

      This snippet configures the URLs invoked by Twilio. It does not change the set of enabled webhook event triggers.
      Loading Code Sample...
          
          
          
          
          To stop receiving webhooks for a particular event, omit that event from the set of WebhookFilters provided here. Only remaining filters will be triggered.

          Enable All Service-level Chat Webhooks

          To stop receiving webhooks for a particular event, omit that event from the set of WebhookFilters provided here. Only remaining filters will be triggered.

          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:

          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
          ClientIdentity 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-Event Webhook Bodies

          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.

          OnUserAdded

          parameter name type description
          UserSid string, SID The SID of the User that was updated.
          EventType string Always onUserAdded
          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
          Attributes JSON, string, optional The optional Attributes of the updated user (if set). JSON structure in string format.

          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.

          Loading Code Sample...