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.

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.

Table of Contents

• Webhook Event Triggers
  • Triggering Webhooks for REST API Events
  • Using Pre-Event Webhooks to Modify or Reject Changes
• Configuring Webhooks with the REST API
• Webhook Bodies by Event Type
  • Pre-Event Webhook Bodies
  • Post-Event Webhook Bodies

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.

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.

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.

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\"}"
}

Selective muting for Push notifications

Additionally, in response to onMessageSend, OnMemberAdd and OnMemberRemove the following property can be modified - mute_notification. This allows to supress Push notification for named events.

HTTP 200 OK
Content-Type: text/json
{
"mute_notification": "true"
}

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.