Skip to content Skip to navigation Skip to topbar

Page tools

On this page

Looking for more inspiration?Visit the

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

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

1https://conversations.twilio.com/v1
2

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:

1GET /v1/Services/ISxx/Conversations/CHxx/Messages
2

Service-Scoped Conversation-Scoped Webhook Properties

Property nameTypeRequiredPIIDescriptionChild properties

sidSID<WH>

Optional

A 34 character string that uniquely identifies this resource.

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

accountSidSID<AC>

Optional

The unique ID of the Account responsible for this conversation.

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

chatServiceSidSID<IS>

Optional

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

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

conversationSidSID<CH>

Optional

The unique ID of the Conversation for this webhook.

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

targetstring

Optional

The target of this webhook: webhook, studio, trigger

urlstring<uri>

Optional

An absolute API resource URL for this webhook.

configuration

Optional

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

dateCreatedstring<date-time>

Optional

The date that this resource was created.

dateUpdatedstring<date-time>

Optional

The date that this resource was last updated.

Create a Service-Scoped Conversation-Scoped Webhook resource

POST https://conversations.twilio.com/v1/Services/{ChatServiceSid}/Conversations/{ConversationSid}/Webhooks

Path parameters

Property nameTypeRequiredPIIDescription

chatServiceSidSID<IS>

required

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

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

conversationSidstring

required

The unique ID of the Conversation for this webhook.

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

targetenum<string>

required

The target of this webhook: webhook, studio, trigger

Possible values:

webhooktriggerstudio

configuration.urlstring

Optional

The absolute url the webhook request should be sent to.

configuration.methodenum<string>

Optional

Possible values:

getpost

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.replayAfterinteger

Optional

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

Create a Webhook

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createServiceConversationScopedWebhook() {
11  const webhook = await client.conversations.v1
12    .services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .conversations("ConversationSid")
14    .webhooks.create({ target: "webhook" });
15
16  console.log(webhook.sid);
17}
18
19createServiceConversationScopedWebhook();

Response

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "conversation_sid": "ConversationSid",
5  "sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6  "target": "webhook",
7  "configuration": {
8    "url": "https://example.com",
9    "method": "get",
10    "filters": [
11      "onMessageSent",
12      "onConversationDestroyed"
13    ]
14  },
15  "date_created": "2016-03-24T21:05:50Z",
16  "date_updated": "2016-03-24T21:05:50Z",
17  "url": "https://conversations.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
18}

Fetch a Service-Scoped Conversation-Scoped Webhook resource

GET https://conversations.twilio.com/v1/Services/{ChatServiceSid}/Conversations/{ConversationSid}/Webhooks/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

chatServiceSidSID<IS>

required

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

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

conversationSidstring

required

The unique ID of the Conversation for this webhook.

sidSID<WH>

required

A 34 character string that uniquely identifies this resource.

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

Fetch a Webhook

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchServiceConversationScopedWebhook() {
11  const webhook = await client.conversations.v1
12    .services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .conversations("ConversationSid")
14    .webhooks("WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
15    .fetch();
16
17  console.log(webhook.sid);
18}
19
20fetchServiceConversationScopedWebhook();

Response

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "conversation_sid": "ConversationSid",
5  "sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6  "target": "studio",
7  "configuration": {
8    "flow_sid": "FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
9  },
10  "date_created": "2016-03-24T21:05:50Z",
11  "date_updated": "2016-03-24T21:05:50Z",
12  "url": "https://conversations.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
13}

Read multiple Service-Scoped Conversation-Scoped Webhook resources

GET https://conversations.twilio.com/v1/Services/{ChatServiceSid}/Conversations/{ConversationSid}/Webhooks

Path parameters

Property nameTypeRequiredPIIDescription

chatServiceSidSID<IS>

required

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

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

conversationSidstring

required

The unique ID of the Conversation for this webhook.

Query parameters

Property nameTypeRequiredPIIDescription

pageSizeinteger<int64>

Optional

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

Minimum: 1Maximum: 5

pageinteger

Optional

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

Minimum: 0

pageTokenstring

Optional

The page token. This is provided by the API.

List multiple Webhooks

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listServiceConversationScopedWebhook() {
11  const webhooks = await client.conversations.v1
12    .services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .conversations("ConversationSid")
14    .webhooks.list({ limit: 20 });
15
16  webhooks.forEach((w) => console.log(w.sid));
17}
18
19listServiceConversationScopedWebhook();

Response

1{
2  "meta": {
3    "page": 0,
4    "page_size": 5,
5    "first_page_url": "https://conversations.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks?PageSize=5&Page=0",
6    "previous_page_url": null,
7    "url": "https://conversations.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks?PageSize=5&Page=0",
8    "next_page_url": null,
9    "key": "webhooks"
10  },
11  "webhooks": [
12    {
13      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14      "chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15      "conversation_sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
16      "sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
17      "target": "webhook",
18      "configuration": {
19        "url": "https://example.com",
20        "method": "get",
21        "filters": [
22          "onMessageSent",
23          "onConversationDestroyed"
24        ]
25      },
26      "date_created": "2016-03-24T21:05:50Z",
27      "date_updated": "2016-03-24T21:05:50Z",
28      "url": "https://conversations.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
29    },
30    {
31      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
32      "chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
33      "conversation_sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
34      "sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
35      "target": "trigger",
36      "configuration": {
37        "url": "https://example.com",
38        "method": "post",
39        "filters": [
40          "keyword1",
41          "keyword2"
42        ]
43      },
44      "date_created": "2016-03-24T21:05:50Z",
45      "date_updated": "2016-03-24T21:05:50Z",
46      "url": "https://conversations.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
47    },
48    {
49      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
50      "chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
51      "conversation_sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
52      "sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
53      "target": "studio",
54      "configuration": {
55        "flow_sid": "FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
56      },
57      "date_created": "2016-03-24T21:05:50Z",
58      "date_updated": "2016-03-24T21:05:50Z",
59      "url": "https://conversations.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
60    }
61  ]
62}

Update a Service-Scoped Conversation-Scoped Webhook resources

POST https://conversations.twilio.com/v1/Services/{ChatServiceSid}/Conversations/{ConversationSid}/Webhooks/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

chatServiceSidSID<IS>

required

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

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

conversationSidstring

required

The unique ID of the Conversation for this webhook.

sidSID<WH>

required

A 34 character string that uniquely identifies this resource.

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

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

configuration.urlstring

Optional

The absolute url the webhook request should be sent to.

configuration.methodenum<string>

Optional

Possible values:

getpost

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

Update a Webhook

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function updateServiceConversationScopedWebhook() {
11  const webhook = await client.conversations.v1
12    .services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .conversations("ConversationSid")
14    .webhooks("WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
15    .update({ "configuration.url": "Configuration.Url" });
16
17  console.log(webhook.sid);
18}
19
20updateServiceConversationScopedWebhook();

Response

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "conversation_sid": "ConversationSid",
5  "sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6  "target": "trigger",
7  "configuration": {
8    "url": "https://example.com",
9    "method": "post",
10    "filters": [
11      "keyword1",
12      "keyword2"
13    ]
14  },
15  "date_created": "2016-03-24T21:05:50Z",
16  "date_updated": "2016-03-24T21:05:51Z",
17  "url": "https://conversations.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
18}

Delete a Service-Scoped, Conversation-Scoped Webhook resource

DELETE https://conversations.twilio.com/v1/Services/{ChatServiceSid}/Conversations/{ConversationSid}/Webhooks/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

chatServiceSidSID<IS>

required

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

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

conversationSidstring

required

The unique ID of the Conversation for this webhook.

sidSID<WH>

required

A 34 character string that uniquely identifies this resource.

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

Delete a Webhook

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function deleteServiceConversationScopedWebhook() {
11  await client.conversations.v1
12    .services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .conversations("ConversationSid")
14    .webhooks("WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
15    .remove();
16}
17
18deleteServiceConversationScopedWebhook();