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

Service-Scoped Conversation-Scoped Webhook Resource

Service-Scoped Conversation-Scoped Webhooks provide a way to attach a unique monitor, bot, or other integration to each service-scoped Conversation within a non-default Conversation Service.

Each individual service-scoped Conversation can have as many as five such webhooks, as needed for your use case.

Please see the API Reference for the Conversation-Scoped Webhook resource for creating and managing Conversation-Scoped Webhooks within the default Conversation Service.

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

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/Messages

Service-Scoped Conversation-Scoped Webhook Properties

service-scoped-conversation-scoped-webhook-properties page anchor
Property nameTypePIIDescription
sidSID<WH>
Not PII

A 34 character string that uniquely identifies this resource.

Pattern: ^WH[0-9a-fA-F]{32}$Min length: 34Max length: 34
account_sidSID<AC>
Not PII

The unique ID of the Account responsible for this conversation.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34
chat_service_sidSID<IS>
Not PII

The SID of the Conversation Service the Participant resource is associated with.

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34
conversation_sidSID<CH>
Not PII

The unique ID of the Conversation for this webhook.

Pattern: ^CH[0-9a-fA-F]{32}$Min length: 34Max length: 34
targetstring
Not PII

The target of this webhook: webhook, studio, trigger

urlstring<uri>
Not PII

An absolute API resource URL for this webhook.

configurationobject
Not PII

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

date_createdstring<date-time>
Not PII

The date that this resource was created.

date_updatedstring<date-time>
Not PII

The date that this resource was last updated.

Create a Service-Scoped Conversation-Scoped Webhook resource

create-a-service-scoped-conversation-scoped-webhook-resource page anchor
POST https://conversations.twilio.com/v1/Services/{ChatServiceSid}/Conversations/{ConversationSid}/Webhooks

Path parameters

path-parameters page anchor
Property nameTypeRequiredPIIDescription
ChatServiceSidSID<IS>required
Not PII

The SID of the Conversation Service the Participant resource is associated with.

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34
ConversationSidstringrequired
Not PII

The unique ID of the Conversation for this webhook.

Request body parameters

request-body-parameters page anchor
Property nameTypeRequiredPIIDescription
Targetenum<string>required
Not PII

The target of this webhook: webhook, studio, trigger

Possible values:
webhooktriggerstudio
Configuration.UrlstringOptional
Not PII

The absolute url the webhook request should be sent to.

Configuration.Methodenum<string>Optional
Not PII

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

Possible values:
GETPOST
Configuration.Filtersarray[string]Optional
Not PII

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

Configuration.Triggersarray[string]Optional
Not PII

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

Configuration.FlowSidSID<FW>Optional
Not PII

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
Not PII

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

Create a ServiceConversationScopedWebhook

create-a-serviceconversationscopedwebhook page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_19
// Download the helper library from https://www.twilio.com/docs/node/install
_19
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_19
_19
// Find your Account SID and Auth Token at twilio.com/console
_19
// and set the environment variables. See http://twil.io/secure
_19
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_19
const authToken = process.env.TWILIO_AUTH_TOKEN;
_19
const client = twilio(accountSid, authToken);
_19
_19
async function createServiceConversationScopedWebhook() {
_19
const webhook = await client.conversations.v1
_19
.services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_19
.conversations("ConversationSid")
_19
.webhooks.create({ target: "studio" });
_19
_19
console.log(webhook.sid);
_19
}
_19
_19
createServiceConversationScopedWebhook();

Output

_18
{
_18
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18
"chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18
"conversation_sid": "ConversationSid",
_18
"sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18
"target": "studio",
_18
"configuration": {
_18
"url": "https://example.com",
_18
"method": "get",
_18
"filters": [
_18
"onMessageSent",
_18
"onConversationDestroyed"
_18
]
_18
},
_18
"date_created": "2016-03-24T21:05:50Z",
_18
"date_updated": "2016-03-24T21:05:50Z",
_18
"url": "https://conversations.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_18
}

Fetch a Service-Scoped Conversation-Scoped Webhook resource

fetch-a-service-scoped-conversation-scoped-webhook-resource page anchor
GET https://conversations.twilio.com/v1/Services/{ChatServiceSid}/Conversations/{ConversationSid}/Webhooks/{Sid}

Path parameters

path-parameters-1 page anchor
Property nameTypeRequiredPIIDescription
ChatServiceSidSID<IS>required
Not PII

The SID of the Conversation Service the Participant resource is associated with.

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34
ConversationSidstringrequired
Not PII

The unique ID of the Conversation for this webhook.

SidSID<WH>required
Not PII

A 34 character string that uniquely identifies this resource.

Pattern: ^WH[0-9a-fA-F]{32}$Min length: 34Max length: 34

Fetch a ServiceConversationScopedWebhook

fetch-a-serviceconversationscopedwebhook page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_20
// Download the helper library from https://www.twilio.com/docs/node/install
_20
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_20
_20
// Find your Account SID and Auth Token at twilio.com/console
_20
// and set the environment variables. See http://twil.io/secure
_20
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_20
const authToken = process.env.TWILIO_AUTH_TOKEN;
_20
const client = twilio(accountSid, authToken);
_20
_20
async function fetchServiceConversationScopedWebhook() {
_20
const webhook = await client.conversations.v1
_20
.services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_20
.conversations("ConversationSid")
_20
.webhooks("WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_20
.fetch();
_20
_20
console.log(webhook.sid);
_20
}
_20
_20
fetchServiceConversationScopedWebhook();

Output

_13
{
_13
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_13
"chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_13
"conversation_sid": "ConversationSid",
_13
"sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_13
"target": "studio",
_13
"configuration": {
_13
"flow_sid": "FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_13
},
_13
"date_created": "2016-03-24T21:05:50Z",
_13
"date_updated": "2016-03-24T21:05:50Z",
_13
"url": "https://conversations.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_13
}

Read multiple Service-Scoped Conversation-Scoped Webhook resources

read-multiple-service-scoped-conversation-scoped-webhook-resources page anchor
GET https://conversations.twilio.com/v1/Services/{ChatServiceSid}/Conversations/{ConversationSid}/Webhooks

Path parameters

path-parameters-2 page anchor
Property nameTypeRequiredPIIDescription
ChatServiceSidSID<IS>required
Not PII

The SID of the Conversation Service the Participant resource is associated with.

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34
ConversationSidstringrequired
Not PII

The unique ID of the Conversation for this webhook.

Query parameters

query-parameters page anchor
Property nameTypeRequiredPIIDescription
PageSizeintegerOptional
Not PII

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

Minimum: 1Maximum: 1000
PageintegerOptional
Not PII

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

Minimum: 0
PageTokenstringOptional
Not PII

The page token. This is provided by the API.

List multiple ServiceConversationScopedWebhooks

list-multiple-serviceconversationscopedwebhooks page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_19
// Download the helper library from https://www.twilio.com/docs/node/install
_19
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_19
_19
// Find your Account SID and Auth Token at twilio.com/console
_19
// and set the environment variables. See http://twil.io/secure
_19
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_19
const authToken = process.env.TWILIO_AUTH_TOKEN;
_19
const client = twilio(accountSid, authToken);
_19
_19
async function listServiceConversationScopedWebhook() {
_19
const webhooks = await client.conversations.v1
_19
.services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_19
.conversations("ConversationSid")
_19
.webhooks.list({ limit: 20 });
_19
_19
webhooks.forEach((w) => console.log(w.sid));
_19
}
_19
_19
listServiceConversationScopedWebhook();

Output

_62
{
_62
"meta": {
_62
"page": 0,
_62
"page_size": 5,
_62
"first_page_url": "https://conversations.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks?PageSize=5&Page=0",
_62
"previous_page_url": null,
_62
"url": "https://conversations.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks?PageSize=5&Page=0",
_62
"next_page_url": null,
_62
"key": "webhooks"
_62
},
_62
"webhooks": [
_62
{
_62
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_62
"chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_62
"conversation_sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_62
"sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_62
"target": "webhook",
_62
"configuration": {
_62
"url": "https://example.com",
_62
"method": "get",
_62
"filters": [
_62
"onMessageSent",
_62
"onConversationDestroyed"
_62
]
_62
},
_62
"date_created": "2016-03-24T21:05:50Z",
_62
"date_updated": "2016-03-24T21:05:50Z",
_62
"url": "https://conversations.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_62
},
_62
{
_62
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_62
"chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_62
"conversation_sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_62
"sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_62
"target": "trigger",
_62
"configuration": {
_62
"url": "https://example.com",
_62
"method": "post",
_62
"filters": [
_62
"keyword1",
_62
"keyword2"
_62
]
_62
},
_62
"date_created": "2016-03-24T21:05:50Z",
_62
"date_updated": "2016-03-24T21:05:50Z",
_62
"url": "https://conversations.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_62
},
_62
{
_62
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_62
"chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_62
"conversation_sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_62
"sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_62
"target": "studio",
_62
"configuration": {
_62
"flow_sid": "FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_62
},
_62
"date_created": "2016-03-24T21:05:50Z",
_62
"date_updated": "2016-03-24T21:05:50Z",
_62
"url": "https://conversations.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_62
}
_62
]
_62
}

Update a Service-Scoped Conversation-Scoped Webhook resources

update-a-service-scoped-conversation-scoped-webhook-resources page anchor
POST https://conversations.twilio.com/v1/Services/{ChatServiceSid}/Conversations/{ConversationSid}/Webhooks/{Sid}

Path parameters

path-parameters-3 page anchor
Property nameTypeRequiredPIIDescription
ChatServiceSidSID<IS>required
Not PII

The SID of the Conversation Service the Participant resource is associated with.

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34
ConversationSidstringrequired
Not PII

The unique ID of the Conversation for this webhook.

SidSID<WH>required
Not PII

A 34 character string that uniquely identifies this resource.

Pattern: ^WH[0-9a-fA-F]{32}$Min length: 34Max length: 34

Request body parameters

request-body-parameters-1 page anchor
Property nameTypeRequiredPIIDescription
Configuration.UrlstringOptional
Not PII

The absolute url the webhook request should be sent to.

Configuration.Methodenum<string>Optional
Not PII

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

Possible values:
GETPOST
Configuration.Filtersarray[string]Optional
Not PII

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

Configuration.Triggersarray[string]Optional
Not PII

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

Configuration.FlowSidSID<FW>Optional
Not PII

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

Pattern: ^FW[0-9a-fA-F]{32}$Min length: 34Max length: 34

Update a ServiceConversationScopedWebhook

update-a-serviceconversationscopedwebhook page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_20
// Download the helper library from https://www.twilio.com/docs/node/install
_20
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_20
_20
// Find your Account SID and Auth Token at twilio.com/console
_20
// and set the environment variables. See http://twil.io/secure
_20
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_20
const authToken = process.env.TWILIO_AUTH_TOKEN;
_20
const client = twilio(accountSid, authToken);
_20
_20
async function updateServiceConversationScopedWebhook() {
_20
const webhook = await client.conversations.v1
_20
.services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_20
.conversations("ConversationSid")
_20
.webhooks("WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_20
.update({ "configuration.url": "Configuration.Url" });
_20
_20
console.log(webhook.sid);
_20
}
_20
_20
updateServiceConversationScopedWebhook();

Output

_18
{
_18
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18
"chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18
"conversation_sid": "ConversationSid",
_18
"sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18
"target": "trigger",
_18
"configuration": {
_18
"url": "https://example.com",
_18
"method": "post",
_18
"filters": [
_18
"keyword1",
_18
"keyword2"
_18
]
_18
},
_18
"date_created": "2016-03-24T21:05:50Z",
_18
"date_updated": "2016-03-24T21:05:51Z",
_18
"url": "https://conversations.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_18
}

Delete a Service-Scoped, Conversation-Scoped Webhook resource

delete-a-service-scoped-conversation-scoped-webhook-resource page anchor
DELETE https://conversations.twilio.com/v1/Services/{ChatServiceSid}/Conversations/{ConversationSid}/Webhooks/{Sid}

Path parameters

path-parameters-4 page anchor
Property nameTypeRequiredPIIDescription
ChatServiceSidSID<IS>required
Not PII

The SID of the Conversation Service the Participant resource is associated with.

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34
ConversationSidstringrequired
Not PII

The unique ID of the Conversation for this webhook.

SidSID<WH>required
Not PII

A 34 character string that uniquely identifies this resource.

Pattern: ^WH[0-9a-fA-F]{32}$Min length: 34Max length: 34

Delete a ServiceConversationScopedWebhook

delete-a-serviceconversationscopedwebhook page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_18
// Download the helper library from https://www.twilio.com/docs/node/install
_18
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_18
_18
// Find your Account SID and Auth Token at twilio.com/console
_18
// and set the environment variables. See http://twil.io/secure
_18
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_18
const authToken = process.env.TWILIO_AUTH_TOKEN;
_18
const client = twilio(accountSid, authToken);
_18
_18
async function deleteServiceConversationScopedWebhook() {
_18
await client.conversations.v1
_18
.services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_18
.conversations("ConversationSid")
_18
.webhooks("WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_18
.remove();
_18
}
_18
_18
deleteServiceConversationScopedWebhook();

Rate this page: