Webhook Configuration Resource

The Webhook Configuration resource allows you to precisely control the effects of account-scoped webhooks. Sending a POST request to the Webhook Configuration endpoint is equivalent to configuring session webhooks in the Twilio Console.

Good applications of the configured webhooks in Conversations include:

Implementing an archival system for all Conversations
Feeding messages into Elasticsearch
Implementing a profanity filter across all Conversations

Note: You can send pre-hooks and post-hooks to different targets.

Our guide to Conversations Webhooks includes the specific pre- and post-event webhooks that fire, as well as the webhook payloads.

Webhook Properties

Property nameTypeRequiredDescriptionChild properties

accountSidSID<AC>

Optional

Not PII

The unique ID of the Account responsible for this conversation.

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

methodenum<string>

Optional

Not PII

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

Possible values:

GETPOST

filtersarray[string]

Optional

Not PII

The list of webhook event triggers that are enabled for this Service: onMessageAdded, onMessageUpdated, onMessageRemoved, onMessageAdd, onMessageUpdate, onMessageRemove, onConversationUpdated, onConversationRemoved, onConversationAdd, onConversationAdded, onConversationRemove, onConversationUpdate, onConversationStateUpdated, onParticipantAdded, onParticipantUpdated, onParticipantRemoved, onParticipantAdd, onParticipantRemove, onParticipantUpdate, onDeliveryUpdated, onUserAdded, onUserUpdate, onUserUpdated

preWebhookUrlstring

Optional

Not PII

The absolute url the pre-event webhook request should be sent to.

postWebhookUrlstring

Optional

Not PII

The absolute url the post-event webhook request should be sent to.

targetenum<string>

Optional

Not PII

The routing target of the webhook. Can be ordinary or route internally to Flex

Possible values:

webhookflex

urlstring<uri>

Optional

Not PII

An absolute API resource API resource URL for this webhook.

Fetch a ConfigurationWebhook resource

GET https://conversations.twilio.com/v1/Configuration/Webhooks

FETCH: Retrieve a Webhook Configuration Resource

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 fetchConfigurationWebhook() {
11  const webhook = await client.conversations.v1.configuration
12    .webhooks()
13    .fetch();
14
15  console.log(webhook.accountSid);
16}
17
18fetchConfigurationWebhook();

Response

Note: This shows the raw API response from Twilio. Responses from SDKs (Java, Python, etc.) may look a little different.

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "pre_webhook_url": "https://example.com/pre",
4  "post_webhook_url": "https://example.com/post",
5  "method": "GET",
6  "filters": [
7    "onMessageSend",
8    "onConversationUpdated"
9  ],
10  "target": "webhook",
11  "url": "https://conversations.twilio.com/v1/Configuration/Webhooks"
12}

Update a ConfigurationWebhook resource

POST https://conversations.twilio.com/v1/Configuration/Webhooks

Request body parameters

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

SchemaExample

Property nameTypeRequiredDescriptionChild properties

methodstring

Optional

Not PII

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

filtersarray[string]

Optional

Not PII

preWebhookUrlstring

Optional

Not PII

The absolute url the pre-event webhook request should be sent to.

postWebhookUrlstring

Optional

Not PII

The absolute url the post-event webhook request should be sent to.

targetenum<string>

Optional

Not PII

The routing target of the webhook. Can be ordinary or route internally to Flex

Possible values:

webhookflex

UPDATE: Enable all Webhooks with filters

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 updateConfigurationWebhook() {
11  const webhook = await client.conversations.v1.configuration
12    .webhooks()
13    .update({
14      filters: ["onConversationUpdated", "onMessageRemoved"],
15      method: "POST",
16      postWebhookUrl: "https://example.com/archive-every-action",
17      preWebhookUrl: "https://example.com/filtering-and-permissions",
18    });
19
20  console.log(webhook.accountSid);
21}
22
23updateConfigurationWebhook();

Response

Note: This shows the raw API response from Twilio. Responses from SDKs (Java, Python, etc.) may look a little different.

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "pre_webhook_url": "https://example.com/filtering-and-permissions",
4  "post_webhook_url": "https://example.com/archive-every-action",
5  "method": "POST",
6  "filters": [
7    "onConversationUpdated"
8  ],
9  "target": "webhook",
10  "url": "https://conversations.twilio.com/v1/Configuration/Webhooks"
11}