Programmable Chat has been deprecated and is no longer supported. Instead, we'll be focusing on the next generation of chat: Twilio Conversations. Find out more about the EOL process here.
If you're starting a new project, please visit the Conversations Docs to begin. If you've already built on Programmable Chat, please visit our Migration Guide to learn about how to switch.
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.
(information)
Info
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.
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.
onMemberUpdate
onMemberUpdated
Fires when Member's attributes are updated.
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. For User's reachability status update only Post-Event webhook is triggered.
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.
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
1
HTTP 200 OK
2
Content-Type: text/json {
3
"friendly_name": "friendly name of channel",
4
"unique_name": "very unique name",
5
"attributes" : "{\"key\" : \"value\"}"
6
}
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.
1
HTTP 200 OK
2
Content-Type: text/json {
3
"body": "modified message text",
4
"attributes": "{\"key\" : \"value\"}"
5
}
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.
1
HTTP 200 OK
2
Content-Type: text/json {
3
"friendly_name": "modified friendly name",
4
"attributes": "{\"key\" : \"value\"}"
5
}
Selective muting for Push notifications
Additionally, in response to onMessageSend, OnMemberAdd and OnMemberRemove the following property can be modified - mute_notification. This allows to suppress Push notification for named events.
1
HTTP 200 OK
2
Content-Type: text/json {
3
"mute_notification": "true"
4
}
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).
Configuring Chat Webhook URLs
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
consttwilio=require("twilio");// Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
"compatibility_message":"new media compatibility message"
56
}
57
}
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)
OnMediaMessageSend
parameter name
type
description
EventType
string
Always onMediaMessageSend
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
MediaFilename
string
The filename of the underlying media file as specified when uploaded
MediaContentType
string
The MIME type of the file this media represents.
MediaSid
string
Media SID identifier
MediaSize
int
Media size in bytes
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)
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)
OnMemberUpdate
parameter name
type
description
EventType
string
Always onMemberUpdate
ChannelSid
string
Channel String Identifier
Identity
string
The Identity of the Member being updated
MemberSid
string
The member SID identifier
RoleSid
string, optional
The role of updated member
DateCreated
string, ISO8601 time
Creation date of member
Attributes
JSON, string, optional
The optional Attributes (if set) of the Member being updated as a JSON structure in string format
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-Event Webhook Bodies
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
OnMediaMessageSent
parameter name
type
description
EventType
string
Always onMediaMessageSent
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
MediaFilename
string
The filename of the underlying media file as specified when uploaded
MediaContentType
string
The MIME type of the file this media represents.
MediaSid
string
Media SID identifier
MediaSize
int
Media size in bytes
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
OnMemberUpdated
parameter name
type
description
EventType
string
Always onMemberUpdated
ChannelSid
string
Channel String Identifier
Identity
string
The Identity of the updated member
MemberSid
string
The member SID identifier
RoleSid
string, optional
The role of updated member
DateCreated
string, ISO8601 time
Creation date of member
DateUpdated
string, ISO8601 time
The date when member was last updated
Attributes
JSON, string, optional
The optional Attributes (if set) of the Member being updated as a JSON structure in string format
LastConsumedMessageIndex
int, optional
Index of the last consumed message by the member
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.
