Conversation Scoped Webhook Resource
Conversation Scoped Webhooks provide a way to attach a unique monitor, bot, or other integration to each conversation.
Each individual Conversation can have as many as five such webhooks, as needed for your use case. This is your go-to tool for adding integrations with third-party bots or Twilio Studio .
For bot integrations, in particular, pay specific attention to the ReplayAfter
parameter to ensure that you don't miss any messages that arrive while you're configuring the integration.
Info Only post-event webhooks are supported by the Conversation-Scoped Webhooks.
All URLs in the reference documentation use the following base URL:
_10 https://conversations.twilio.com/v1
Using the REST API, you can interact with Conversation Scoped Webhook resources in the default Conversation Service instance via a "shortened" URL that does not include the Conversation Service instance SID ("ISXXX..."). If you are only using one Conversation Service (the default), you do not need to include the Conversation Service SID in your URL, e.g.
_10 GET /v1/Conversations/CHxxx/Webhooks
For Conversations applications that build on more than one Conversation Service instance, you will need to specify the Conversation Service SID in the REST API call:
_10 GET /v1/Services/ISxx/Conversations/CHxx/Webhooks
Resource properties A 34 character string that uniquely identifies this resource.
conversation_sid
type: SID<CH> Not PIIThe target of this webhook: webhook
, studio
, trigger
An absolute API resource URL for this webhook.
The configuration of this webhook. Is defined based on target.
date_created
type: string<DATE TIME> Not PIIThe date that this resource was created.
date_updated
type: string<DATE TIME> Not PIIThe date that this resource was last updated.
POST https://conversations.twilio.com/v1/Conversations/{ConversationSid}/Webhooks
URI parameters Request body parameters Required
The target of this webhook: webhook
, studio
, trigger
Possible values:
webhook
trigger
studio
Configuration.Url
type: string Not PIIThe absolute url the webhook request should be sent to.
Configuration.Method
type: enum<STRING> Not PIIThe HTTP method to be used when sending a webhook request.
Configuration.Filters
type: string[] Not PIIThe list of events, firing webhook event for this Conversation.
Configuration.Triggers
type: string[] Not PIIThe list of keywords, firing webhook event for this Conversation.
Configuration.FlowSid
type: SID<FW> Not PIIThe studio flow SID, where the webhook should be sent to.
Configuration.ReplayAfter
type: integer Not PIIThe message index for which and it's successors the webhook will be replayed. Not set by default
_16 // Download the helper library from https://www.twilio.com/docs/node/install
_16 // Find your Account SID and Auth Token at twilio.com/console
_16 // and set the environment variables. See http://twil.io/secure
_16 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_16 const authToken = process.env.TWILIO_AUTH_TOKEN;
_16 const client = require('twilio')(accountSid, authToken);
_16 client.conversations.v1.conversations('CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_16 'configuration.method': 'GET',
_16 'configuration.filters': ['onMessageAdded', 'onConversationRemoved'],
_16 'configuration.url': 'https://example.com',
_16 .then(webhook => console.log(webhook.sid));
_17 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17 "conversation_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17 "sid": "WHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17 "url": "https://example.com",
_17 "onConversationDestroyed"
_17 "date_created": "2016-03-24T21:05:50Z",
_17 "date_updated": "2016-03-24T21:05:50Z",
_17 "url": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Webhooks/WHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
GET https://conversations.twilio.com/v1/Conversations/{ConversationSid}/Webhooks/{Sid}
URI parameters Path Parameter
A 34 character string that uniquely identifies this resource.
_11 // Download the helper library from https://www.twilio.com/docs/node/install
_11 // Find your Account SID and Auth Token at twilio.com/console
_11 // and set the environment variables. See http://twil.io/secure
_11 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11 const authToken = process.env.TWILIO_AUTH_TOKEN;
_11 const client = require('twilio')(accountSid, authToken);
_11 client.conversations.v1.conversations('CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11 .webhooks('WHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11 .then(webhook => console.log(webhook.sid));
_12 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_12 "conversation_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_12 "sid": "WHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_12 "flow_sid": "FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_12 "date_created": "2016-03-24T21:05:50Z",
_12 "date_updated": "2016-03-24T21:05:50Z",
_12 "url": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Webhooks/WHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
GET https://conversations.twilio.com/v1/Conversations/{ConversationSid}/Webhooks
URI parameters Query Parameter
How many resources to return in each list page. The default is 50, and the maximum is 1000.
Query Parameter
The page index. This value is simply for client state.
Query Parameter
The page token. This is provided by the API.
_11 // Download the helper library from https://www.twilio.com/docs/node/install
_11 // Find your Account SID and Auth Token at twilio.com/console
_11 // and set the environment variables. See http://twil.io/secure
_11 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11 const authToken = process.env.TWILIO_AUTH_TOKEN;
_11 const client = require('twilio')(accountSid, authToken);
_11 client.conversations.v1.conversations('CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11 .then(webhooks => webhooks.forEach(w => console.log(w.sid)));
_59 "first_page_url": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Webhooks?PageSize=5&Page=0",
_59 "previous_page_url": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Webhooks?PageSize=5&Page=0",
_59 "url": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Webhooks?PageSize=5&Page=0",
_59 "next_page_url": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Webhooks?PageSize=5&Page=1",
_59 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_59 "conversation_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_59 "sid": "WHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_59 "url": "https://example.com",
_59 "onConversationDestroyed"
_59 "date_created": "2016-03-24T21:05:50Z",
_59 "date_updated": "2016-03-24T21:05:50Z",
_59 "url": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Webhooks/WHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_59 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_59 "conversation_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_59 "sid": "WHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_59 "url": "https://example.com",
_59 "date_created": "2016-03-24T21:05:50Z",
_59 "date_updated": "2016-03-24T21:05:50Z",
_59 "url": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Webhooks/WHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_59 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_59 "conversation_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_59 "sid": "WHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_59 "flow_sid": "FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_59 "date_created": "2016-03-24T21:05:50Z",
_59 "date_updated": "2016-03-24T21:05:50Z",
_59 "url": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Webhooks/WHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
POST https://conversations.twilio.com/v1/Conversations/{ConversationSid}/Webhooks/{Sid}
URI parameters Path Parameter
A 34 character string that uniquely identifies this resource.
Request body parameters Configuration.Url
type: string Not PIIThe absolute url the webhook request should be sent to.
Configuration.Method
type: enum<STRING> Not PIIThe HTTP method to be used when sending a webhook request.
Configuration.Filters
type: string[] Not PIIThe list of events, firing webhook event for this Conversation.
Configuration.Triggers
type: string[] Not PIIThe list of keywords, firing webhook event for this Conversation.
Configuration.FlowSid
type: SID<FW> Not PIIThe studio flow SID, where the webhook should be sent to.
_13 // Download the helper library from https://www.twilio.com/docs/node/install
_13 // Find your Account SID and Auth Token at twilio.com/console
_13 // and set the environment variables. See http://twil.io/secure
_13 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_13 const authToken = process.env.TWILIO_AUTH_TOKEN;
_13 const client = require('twilio')(accountSid, authToken);
_13 client.conversations.v1.conversations('CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_13 .webhooks('WHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_13 'configuration.filters': ['keyword1', 'keyword2']
_13 .then(webhook => console.log(webhook.configuration));
_17 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17 "conversation_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17 "sid": "WHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17 "url": "https://example.com",
_17 "date_created": "2016-03-24T21:05:50Z",
_17 "date_updated": "2016-03-24T21:05:51Z",
_17 "url": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Webhooks/WHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
DELETE https://conversations.twilio.com/v1/Conversations/{ConversationSid}/Webhooks/{Sid}
URI parameters Path Parameter
A 34 character string that uniquely identifies this resource.
_10 // Download the helper library from https://www.twilio.com/docs/node/install
_10 // Find your Account SID and Auth Token at twilio.com/console
_10 // and set the environment variables. See http://twil.io/secure
_10 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10 const authToken = process.env.TWILIO_AUTH_TOKEN;
_10 const client = require('twilio')(accountSid, authToken);
_10 client.conversations.v1.conversations('CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10 .webhooks('WHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')