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:
_10https://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.
_10GET /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:
_10GET /v1/Services/ISxx/Conversations/CHxx/Webhooks
Property nameTypePIIDescription
A 34 character string that uniquely identifies this resource.
Pattern: ^WH[0-9a-fA-F]{32}$Min length: 34Max length: 34
The unique ID of the Account responsible for this conversation.
Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34
The unique ID of the Conversation for this webhook.
Pattern: ^CH[0-9a-fA-F]{32}$Min length: 34Max length: 34
The 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_createdstring<date-time> The date that this resource was created.
date_updatedstring<date-time> The date that this resource was last updated.
POST https://conversations.twilio.com/v1/Conversations/{ConversationSid}/Webhooks
Property nameTypeRequiredPIIDescription
ConversationSidstringrequired Property nameTypeRequiredPIIDescription
Targetenum<string>required The target of this webhook: webhook, studio, trigger
Possible values: webhooktriggerstudio
Configuration.UrlstringOptional The absolute url the webhook request should be sent to.
Configuration.Methodenum<string>Optional The HTTP method to be used when sending a webhook request.
Configuration.Filtersarray[string]Optional The list of events, firing webhook event for this Conversation.
Configuration.Triggersarray[string]Optional The list of keywords, firing webhook event for this Conversation.
Configuration.FlowSidSID<FW>Optional The studio flow SID, where the webhook should be sent to.
Pattern: ^FW[0-9a-fA-F]{32}$Min length: 34Max length: 34
Configuration.ReplayAfterintegerOptional The message index for which and it's successors the webhook will be replayed. Not set by default
_23// Download the helper library from https://www.twilio.com/docs/node/install
_23const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_23// Find your Account SID and Auth Token at twilio.com/console
_23// and set the environment variables. See http://twil.io/secure
_23const accountSid = process.env.TWILIO_ACCOUNT_SID;
_23const authToken = process.env.TWILIO_AUTH_TOKEN;
_23const client = twilio(accountSid, authToken);
_23async function createConversationScopedWebhook() {
_23 const webhook = await client.conversations.v1
_23 .conversations("ConversationSid")
_23 "configuration.filters": ["onMessageAdded", "onConversationRemoved"],
_23 "configuration.method": "GET",
_23 "configuration.url": "https://example.com",
_23 console.log(webhook.sid);
_23createConversationScopedWebhook();
_17 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_17 "conversation_sid": "ConversationSid",
_17 "sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_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/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
GET https://conversations.twilio.com/v1/Conversations/{ConversationSid}/Webhooks/{Sid}
Property nameTypeRequiredPIIDescription
ConversationSidstringrequired
A 34 character string that uniquely identifies this resource.
Pattern: ^WH[0-9a-fA-F]{32}$Min length: 34Max length: 34
_19// Download the helper library from https://www.twilio.com/docs/node/install
_19const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_19// Find your Account SID and Auth Token at twilio.com/console
_19// and set the environment variables. See http://twil.io/secure
_19const accountSid = process.env.TWILIO_ACCOUNT_SID;
_19const authToken = process.env.TWILIO_AUTH_TOKEN;
_19const client = twilio(accountSid, authToken);
_19async function fetchConversationScopedWebhook() {
_19 const webhook = await client.conversations.v1
_19 .conversations("ConversationSid")
_19 .webhooks("WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_19 console.log(webhook.sid);
_19fetchConversationScopedWebhook();
_12 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_12 "conversation_sid": "ConversationSid",
_12 "sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_12 "flow_sid": "FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_12 "date_created": "2016-03-24T21:05:50Z",
_12 "date_updated": "2016-03-24T21:05:50Z",
_12 "url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
GET https://conversations.twilio.com/v1/Conversations/{ConversationSid}/Webhooks
Property nameTypeRequiredPIIDescription
ConversationSidstringrequired Property nameTypeRequiredPIIDescription
How many resources to return in each list page. The default is 50, and the maximum is 1000.
Minimum: 1Maximum: 1000
The page index. This value is simply for client state.
Minimum: 0
The page token. This is provided by the API.
_18// Download the helper library from https://www.twilio.com/docs/node/install
_18const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_18// Find your Account SID and Auth Token at twilio.com/console
_18// and set the environment variables. See http://twil.io/secure
_18const accountSid = process.env.TWILIO_ACCOUNT_SID;
_18const authToken = process.env.TWILIO_AUTH_TOKEN;
_18const client = twilio(accountSid, authToken);
_18async function listConversationScopedWebhook() {
_18 const webhooks = await client.conversations.v1
_18 .conversations("ConversationSid")
_18 .webhooks.list({ limit: 20 });
_18 webhooks.forEach((w) => console.log(w.sid));
_18listConversationScopedWebhook();
_59 "first_page_url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks?PageSize=5&Page=0",
_59 "previous_page_url": null,
_59 "url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks?PageSize=5&Page=0",
_59 "next_page_url": null,
_59 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_59 "conversation_sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_59 "sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_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/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_59 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_59 "conversation_sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_59 "sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_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/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_59 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_59 "conversation_sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_59 "sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_59 "flow_sid": "FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_59 "date_created": "2016-03-24T21:05:50Z",
_59 "date_updated": "2016-03-24T21:05:50Z",
_59 "url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
POST https://conversations.twilio.com/v1/Conversations/{ConversationSid}/Webhooks/{Sid}
Property nameTypeRequiredPIIDescription
ConversationSidstringrequired
A 34 character string that uniquely identifies this resource.
Pattern: ^WH[0-9a-fA-F]{32}$Min length: 34Max length: 34
Property nameTypeRequiredPIIDescription
Configuration.UrlstringOptional The absolute url the webhook request should be sent to.
Configuration.Methodenum<string>Optional The HTTP method to be used when sending a webhook request.
Configuration.Filtersarray[string]Optional The list of events, firing webhook event for this Conversation.
Configuration.Triggersarray[string]Optional The list of keywords, firing webhook event for this Conversation.
Configuration.FlowSidSID<FW>Optional The studio flow SID, where the webhook should be sent to.
Pattern: ^FW[0-9a-fA-F]{32}$Min length: 34Max length: 34
_19// Download the helper library from https://www.twilio.com/docs/node/install
_19const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_19// Find your Account SID and Auth Token at twilio.com/console
_19// and set the environment variables. See http://twil.io/secure
_19const accountSid = process.env.TWILIO_ACCOUNT_SID;
_19const authToken = process.env.TWILIO_AUTH_TOKEN;
_19const client = twilio(accountSid, authToken);
_19async function updateConversationScopedWebhook() {
_19 const webhook = await client.conversations.v1
_19 .conversations("ConversationSid")
_19 .webhooks("WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_19 .update({ "configuration.filters": ["keyword1", "keyword2"] });
_19 console.log(webhook.configuration);
_19updateConversationScopedWebhook();
_17 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_17 "conversation_sid": "ConversationSid",
_17 "sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_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/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
DELETE https://conversations.twilio.com/v1/Conversations/{ConversationSid}/Webhooks/{Sid}
Property nameTypeRequiredPIIDescription
ConversationSidstringrequired
A 34 character string that uniquely identifies this resource.
Pattern: ^WH[0-9a-fA-F]{32}$Min length: 34Max length: 34
_17// Download the helper library from https://www.twilio.com/docs/node/install
_17const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_17// Find your Account SID and Auth Token at twilio.com/console
_17// and set the environment variables. See http://twil.io/secure
_17const accountSid = process.env.TWILIO_ACCOUNT_SID;
_17const authToken = process.env.TWILIO_AUTH_TOKEN;
_17const client = twilio(accountSid, authToken);
_17async function deleteConversationScopedWebhook() {
_17 await client.conversations.v1
_17 .conversations("ConversationSid")
_17 .webhooks("WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_17deleteConversationScopedWebhook();