Skip to content Skip to navigation Skip to topbar

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

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


_10https://conversations.twilio.com/v1

Using the shortened base URL

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

Webhook Properties

Property nameTypeRequiredDescriptionChild 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

account_sidSID<AC>Optional

The unique ID of the Account responsible for this conversation.

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

conversation_sidSID<CH>Optional

The unique ID of the Conversation for this webhook.

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

targetstringOptional

The target of this webhook: webhook, studio, trigger

urlstring<uri>Optional

An absolute API resource URL for this webhook.

configurationobjectOptional

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

date_createdstring<date-time>Optional

The date that this resource was created.

date_updatedstring<date-time>Optional

The date that this resource was last updated.

Create a ConversationScopedWebhook resource

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

Path parameters

Property nameTypeRequiredPIIDescription

ConversationSidstringrequired

The unique ID of the Conversation for this webhook.

Request body parameters

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

SchemaExample

Property nameTypeRequiredDescriptionChild properties

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.

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

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

Node.js

Python

C#

Java

Go

PHP

Ruby

twilio-cli

curl


_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
_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);
_23
_23async function createConversationScopedWebhook() {
_23  const webhook = await client.conversations.v1
_23    .conversations("ConversationSid")
_23    .webhooks.create({
_23      "configuration.filters": ["onMessageAdded", "onConversationRemoved"],
_23      "configuration.method": "GET",
_23      "configuration.url": "https://example.com",
_23      target: "webhook",
_23    });
_23
_23  console.log(webhook.sid);
_23}
_23
_23createConversationScopedWebhook();

Output


_17{
_17  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_17  "conversation_sid": "ConversationSid",
_17  "sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_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/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_17}

Fetch a ConversationScopedWebhook resource

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

Path parameters

Property nameTypeRequiredPIIDescription

ConversationSidstringrequired

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: Retrieve a Conversation Scoped Webhook

Node.js

Python

C#

Java

Go

PHP

Ruby

twilio-cli

curl


_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
_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);
_19
_19async function fetchConversationScopedWebhook() {
_19  const webhook = await client.conversations.v1
_19    .conversations("ConversationSid")
_19    .webhooks("WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_19    .fetch();
_19
_19  console.log(webhook.sid);
_19}
_19
_19fetchConversationScopedWebhook();

Output


_12{
_12  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_12  "conversation_sid": "ConversationSid",
_12  "sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_12  "target": "studio",
_12  "configuration": {
_12    "flow_sid": "FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_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/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_12}

Read multiple ConversationScopedWebhook resources

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

Path parameters

Property nameTypeRequiredPIIDescription

ConversationSidstringrequired

The unique ID of the Conversation for this webhook.

Query parameters

Property nameTypeRequiredPIIDescription

PageSizeintegerOptional

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

Minimum: 1Maximum: 1000

PageintegerOptional

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

Minimum: 0

PageTokenstringOptional

The page token. This is provided by the API.

READ: List all Conversation Scoped Webhooks

Node.js

Python

C#

Java

Go

PHP

Ruby

twilio-cli

curl


_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
_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);
_18
_18async function listConversationScopedWebhook() {
_18  const webhooks = await client.conversations.v1
_18    .conversations("ConversationSid")
_18    .webhooks.list({ limit: 20 });
_18
_18  webhooks.forEach((w) => console.log(w.sid));
_18}
_18
_18listConversationScopedWebhook();

Output


_59{
_59  "meta": {
_59    "page": 0,
_59    "page_size": 5,
_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    "key": "webhooks"
_59  },
_59  "webhooks": [
_59    {
_59      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_59      "conversation_sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_59      "sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_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/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_59    },
_59    {
_59      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_59      "conversation_sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_59      "sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_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/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_59    },
_59    {
_59      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_59      "conversation_sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_59      "sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_59      "target": "studio",
_59      "configuration": {
_59        "flow_sid": "FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_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/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_59    }
_59  ]
_59}

Update a ConversationScopedWebhook resource

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

Path parameters

Property nameTypeRequiredPIIDescription

ConversationSidstringrequired

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 nameTypeRequiredDescriptionChild properties

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.

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: Configure a Conversation Scoped Webhook

Node.js

Python

C#

Java

Go

PHP

Ruby

twilio-cli

curl


_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
_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);
_19
_19async function updateConversationScopedWebhook() {
_19  const webhook = await client.conversations.v1
_19    .conversations("ConversationSid")
_19    .webhooks("WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_19    .update({ "configuration.filters": ["keyword1", "keyword2"] });
_19
_19  console.log(webhook.configuration);
_19}
_19
_19updateConversationScopedWebhook();

Output


_17{
_17  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_17  "conversation_sid": "ConversationSid",
_17  "sid": "WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_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/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_17}

Delete a ConversationScopedWebhook resource

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

Path parameters

Property nameTypeRequiredPIIDescription

ConversationSidstringrequired

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: Detach a Conversation Scoped Webhook

Node.js

Python

C#

Java

Go

PHP

Ruby

twilio-cli

curl


_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
_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);
_17
_17async function deleteConversationScopedWebhook() {
_17  await client.conversations.v1
_17    .conversations("ConversationSid")
_17    .webhooks("WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_17    .remove();
_17}
_17
_17deleteConversationScopedWebhook();