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
Resource properties
sid
type: SID<WH>
A 34 character string that uniquely identifies this resource.
Pattern:
^WH[0-9a-fA-F]{32}$
conversation_sid
type: SID<CH>
target
type: string
The target of this webhook: webhook
, studio
, trigger
url
type: string<uri>
An absolute API resource URL for this webhook.
configuration
type: object
The configuration of this webhook. Is defined based on target.
date_created
type: string<date-time>
The date that this resource was created.
date_updated
type: string<date-time>
The date that this resource was last updated.
POST https://conversations.twilio.com/v1/Conversations/{ConversationSid}/Webhooks
URI parameters
ConversationSid
type: string
Request body parameters
Target
type: enum<string>Required
The target of this webhook: webhook
, studio
, trigger
Possible values:
webhook
trigger
studio
Configuration.Url
type: string
The absolute url the webhook request should be sent to.
Configuration.Method
type: enum<string>
The HTTP method to be used when sending a webhook request.
Configuration.Filters
type: array[string]
The list of events, firing webhook event for this Conversation.
Configuration.Triggers
type: array[string]
The list of keywords, firing webhook event for this Conversation.
Configuration.FlowSid
type: SID<FW>
The studio flow SID, where the webhook should be sent to.
Pattern:
^FW[0-9a-fA-F]{32}$
Configuration.ReplayAfter
type: integer
The 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
_16const accountSid = process.env.TWILIO_ACCOUNT_SID;
_16const authToken = process.env.TWILIO_AUTH_TOKEN;
_16const client = require('twilio')(accountSid, authToken);
_16client.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
ConversationSid
type: string
Sid
type: SID<WH>
A 34 character string that uniquely identifies this resource.
Pattern:
^WH[0-9a-fA-F]{32}$
_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
_11const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11const authToken = process.env.TWILIO_AUTH_TOKEN;
_11const client = require('twilio')(accountSid, authToken);
_11client.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
ConversationSid
type: string
PageSize
type: integer
How many resources to return in each list page. The default is 50, and the maximum is 1000.
Page
type: integer
The page index. This value is simply for client state.
PageToken
type: string
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
_11const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11const authToken = process.env.TWILIO_AUTH_TOKEN;
_11const client = require('twilio')(accountSid, authToken);
_11client.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
ConversationSid
type: string
Sid
type: SID<WH>
A 34 character string that uniquely identifies this resource.
Pattern:
^WH[0-9a-fA-F]{32}$
Request body parameters
Configuration.Url
type: string
The absolute url the webhook request should be sent to.
Configuration.Method
type: enum<string>
The HTTP method to be used when sending a webhook request.
Configuration.Filters
type: array[string]
The list of events, firing webhook event for this Conversation.
Configuration.Triggers
type: array[string]
The list of keywords, firing webhook event for this Conversation.
Configuration.FlowSid
type: SID<FW>
The studio flow SID, where the webhook should be sent to.
Pattern:
^FW[0-9a-fA-F]{32}$
_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
_13const accountSid = process.env.TWILIO_ACCOUNT_SID;
_13const authToken = process.env.TWILIO_AUTH_TOKEN;
_13const client = require('twilio')(accountSid, authToken);
_13client.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
ConversationSid
type: string
Sid
type: SID<WH>
A 34 character string that uniquely identifies this resource.
Pattern:
^WH[0-9a-fA-F]{32}$
_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
_10const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10const authToken = process.env.TWILIO_AUTH_TOKEN;
_10const client = require('twilio')(accountSid, authToken);
_10client.conversations.v1.conversations('CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10 .webhooks('WHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')