Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

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.

(information)

Info

Only post-event webhooks are supported by the Conversation-Scoped Webhooks.


API Base URL

api-base-url page anchor

All URLs in the reference documentation use the following base URL:


_10
https://conversations.twilio.com/v1

Using the shortened base URL

using-the-shortened-base-url page anchor

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


ConversationScopedWebhook Properties

conversationscopedwebhook-properties page anchor
Resource properties
sidtype: SID<WH>Not PII

A 34 character string that uniquely identifies this resource.


conversation_sidtype: SID<CH>Not PII

The unique ID of the Conversation(link takes you to an external page) for this webhook.


targettype: stringNot PII

The target of this webhook: webhook, studio, trigger


urltype: string<URI>Not PII

An absolute API resource URL for this webhook.


configurationtype: objectNot PII

The configuration of this webhook. Is defined based on target.


date_createdtype: string<DATE TIME>Not PII

The date that this resource was created.


date_updatedtype: string<DATE TIME>Not PII

The date that this resource was last updated.


Create a ConversationScopedWebhook resource

create-a-conversationscopedwebhook-resource page anchor
POST https://conversations.twilio.com/v1/Conversations/{ConversationSid}/Webhooks

Parameters

create-parameters page anchor
URI parameters
ConversationSidtype: stringNot PII
Path Parameter

The unique ID of the Conversation(link takes you to an external page) for this webhook.


Request body parameters
Targettype: enum<STRING>Not PII
Required

The target of this webhook: webhook, studio, trigger

Possible values:
webhooktriggerstudio

Configuration.Urltype: stringNot PII

The absolute url the webhook request should be sent to.


Configuration.Methodtype: enum<STRING>Not PII

The HTTP method to be used when sending a webhook request.

Possible values:
GETPOST

Configuration.Filterstype: string[]Not PII

The list of events, firing webhook event for this Conversation.


Configuration.Triggerstype: string[]Not PII

The list of keywords, firing webhook event for this Conversation.


Configuration.FlowSidtype: SID<FW>Not PII

The studio flow SID, where the webhook should be sent to.


Configuration.ReplayAftertype: integerNot PII

The message index for which and it's successors the webhook will be replayed. Not set by default

CREATE: Attach a new Conversation Scoped Webhook

create-attach-a-new-conversation-scoped-webhook page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_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
_16
client.conversations.v1.conversations('CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_16
.webhooks
_16
.create({
_16
'configuration.method': 'GET',
_16
'configuration.filters': ['onMessageAdded', 'onConversationRemoved'],
_16
'configuration.url': 'https://example.com',
_16
target: 'webhook'
_16
})
_16
.then(webhook => console.log(webhook.sid));

Output

_17
{
_17
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17
"conversation_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17
"sid": "WHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17
"target": "webhook",
_17
"configuration": {
_17
"url": "https://example.com",
_17
"method": "get",
_17
"filters": [
_17
"onMessageSent",
_17
"onConversationDestroyed"
_17
]
_17
},
_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"
_17
}


Fetch a ConversationScopedWebhook resource

fetch-a-conversationscopedwebhook-resource page anchor
GET https://conversations.twilio.com/v1/Conversations/{ConversationSid}/Webhooks/{Sid}

URI parameters
ConversationSidtype: stringNot PII
Path Parameter

The unique ID of the Conversation(link takes you to an external page) for this webhook.


Sidtype: SID<WH>Not PII
Path Parameter

A 34 character string that uniquely identifies this resource.

FETCH: Retrieve a Conversation Scoped Webhook

fetch-retrieve-a-conversation-scoped-webhook page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_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
_11
client.conversations.v1.conversations('CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.webhooks('WHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.fetch()
_11
.then(webhook => console.log(webhook.sid));

Output

_12
{
_12
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_12
"conversation_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_12
"sid": "WHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_12
"target": "studio",
_12
"configuration": {
_12
"flow_sid": "FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_12
},
_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"
_12
}


Read multiple ConversationScopedWebhook resources

read-multiple-conversationscopedwebhook-resources page anchor
GET https://conversations.twilio.com/v1/Conversations/{ConversationSid}/Webhooks

URI parameters
ConversationSidtype: stringNot PII
Path Parameter

The unique ID of the Conversation(link takes you to an external page) for this webhook.


PageSizetype: integerNot PII
Query Parameter

How many resources to return in each list page. The default is 50, and the maximum is 1000.


Pagetype: integerNot PII
Query Parameter

The page index. This value is simply for client state.


PageTokentype: stringNot PII
Query Parameter

The page token. This is provided by the API.

READ: List all Conversation Scoped Webhooks

read-list-all-conversation-scoped-webhooks page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_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
_11
client.conversations.v1.conversations('CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.webhooks
_11
.list({limit: 20})
_11
.then(webhooks => webhooks.forEach(w => console.log(w.sid)));

Output

_59
{
_59
"meta": {
_59
"page": 0,
_59
"page_size": 5,
_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
"key": "webhooks"
_59
},
_59
"webhooks": [
_59
{
_59
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_59
"conversation_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_59
"sid": "WHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_59
"target": "webhook",
_59
"configuration": {
_59
"url": "https://example.com",
_59
"method": "get",
_59
"filters": [
_59
"onMessageSent",
_59
"onConversationDestroyed"
_59
]
_59
},
_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
},
_59
{
_59
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_59
"conversation_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_59
"sid": "WHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_59
"target": "trigger",
_59
"configuration": {
_59
"url": "https://example.com",
_59
"method": "post",
_59
"filters": [
_59
"keyword1",
_59
"keyword2"
_59
]
_59
},
_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
},
_59
{
_59
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_59
"conversation_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_59
"sid": "WHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_59
"target": "studio",
_59
"configuration": {
_59
"flow_sid": "FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_59
},
_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
}
_59
]
_59
}


Update a ConversationScopedWebhook resource

update-a-conversationscopedwebhook-resource page anchor
POST https://conversations.twilio.com/v1/Conversations/{ConversationSid}/Webhooks/{Sid}

URI parameters
ConversationSidtype: stringNot PII
Path Parameter

The unique ID of the Conversation(link takes you to an external page) for this webhook.


Sidtype: SID<WH>Not PII
Path Parameter

A 34 character string that uniquely identifies this resource.


Request body parameters
Configuration.Urltype: stringNot PII

The absolute url the webhook request should be sent to.


Configuration.Methodtype: enum<STRING>Not PII

The HTTP method to be used when sending a webhook request.

Possible values:
GETPOST

Configuration.Filterstype: string[]Not PII

The list of events, firing webhook event for this Conversation.


Configuration.Triggerstype: string[]Not PII

The list of keywords, firing webhook event for this Conversation.


Configuration.FlowSidtype: SID<FW>Not PII

The studio flow SID, where the webhook should be sent to.

UPDATE: Configure a Conversation Scoped Webhook

update-configure-a-conversation-scoped-webhook page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_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
_13
client.conversations.v1.conversations('CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_13
.webhooks('WHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_13
.update({
_13
'configuration.filters': ['keyword1', 'keyword2']
_13
})
_13
.then(webhook => console.log(webhook.configuration));

Output

_17
{
_17
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17
"conversation_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17
"sid": "WHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17
"target": "trigger",
_17
"configuration": {
_17
"url": "https://example.com",
_17
"method": "post",
_17
"filters": [
_17
"keyword1",
_17
"keyword2"
_17
]
_17
},
_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"
_17
}


Delete a ConversationScopedWebhook resource

delete-a-conversationscopedwebhook-resource page anchor
DELETE https://conversations.twilio.com/v1/Conversations/{ConversationSid}/Webhooks/{Sid}

URI parameters
ConversationSidtype: stringNot PII
Path Parameter

The unique ID of the Conversation(link takes you to an external page) for this webhook.


Sidtype: SID<WH>Not PII
Path Parameter

A 34 character string that uniquely identifies this resource.

DELETE: Detach a Conversation Scoped Webhook

delete-detach-a-conversation-scoped-webhook page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_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
_10
client.conversations.v1.conversations('CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.webhooks('WHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.remove();


Rate this page: