Conversations Webhooks

• Configuring Webhook Targets and Filtering

• Webhook Action Triggers

• Using Pre-Action Webhooks to Modify or Reject Changes

• Configuring Webhooks with the REST API

• Webhooks by Event Type

  • Pre-Action Webhook Bodies
  • Post-Action Webhook Bodies

You can configure the global (Account-level) webhook target and service-level webhook target through the Console, or through the REST API.

• For the global webhook target, go to Conversations > Global webhooks.
• For the service-level webhook target, select your Conversation Service, then go to Webhooks.

Expand image

Note: The Conversation-scoped webhooks may only be modified via the REST API.

In addition to configuring the URLs for pre-action and post-action webhooks, you can also choose to send only certain webhooks to your servers. This helps avoid unnecessarily burdening your web application with traffic.

These can also be configured at an account level (globally) or at the service level in the Twilio Console:

• For the global webhook target, go to Conversations > Global webhooks and scroll down to Webhook Filtering.
• For the service-level webhook target, select your Conversation Service, then go to Webhooks. Scroll down to Webhook Filtering.

Expand image

Most actions — but not all of them — have both a pre-action and a post-action webhook. The former is fired before the action has been published, and Twilio waits for a response before publishing it. The latter is fired after publication, assuming the action was not rejected by your pre-action webhook response.

The below table enumerates all Conversations webhook actions in corresponding pairs.

Upon configuration, only actions from SDK-driven clients (like mobile phones or browsers) or SMS-based Participants will cause webhooks without further action on your part. This includes both Service-level webhooks and Conversation-Scoped Webhooks. This is a default behavior to help avoid infinite feedback loops.

Your Post-Event Webhook target, however, may be an important tool for archiving. In this case, you may also want to enable webhook "echoes" from actions you take on the REST API. To do so, you can add a header X-Twilio-Webhook-Enabled=true to any such request. Requests bearing this header will yield webhooks to the configured Post-Event webhook target.

In the case of Pre-Action webhooks, Twilio will wait for a response from your service before publishing a result. The arrival, HTTP status code, and content of your response determines how Conversations will proceed.

In response to the onConversationAdd and onConversationUpdate actions, your Pre-Action Webhook response may modify the following property of the conversation:

• friendly_name

An example response modifying a conversation

1
HTTP 200 OK
2
Content-Type: application/json
3
{
4
    "friendly_name": "friendly name of conversation"
5
}

In response to onMessageAdd and onMessageUpdate actions, your Pre-Action Webhook response may modify the following properties of the message:

• body
• author
• attributes

An example response modifying a message.

1
HTTP 200 OK
2
Content-Type: application/json
3
{
4
    "body": "modified message text",
5
    "author": "modified author name",
6
    "attributes": "{\"key\" : \"value\"}"
7
}

Your Conversations service can have global webhooks that apply to every conversation within the service, or you can specify webhooks per conversation.

Post-action webhooks are available for all three types of webhooks (global, service-level and conversation-scoped). Pre-action webhooks are only available for two types of webhooks (global and service-level).

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const 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
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function fetchConfigurationWebhook() {
11
  const webhook = await client.conversations.v1.configuration
12
    .webhooks()
13
    .fetch();
14

15
  console.log(webhook.accountSid);
16
}
17

18
fetchConfigurationWebhook();

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
}

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const 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
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function updateConfigurationWebhook() {
11
  const webhook = await client.conversations.v1.configuration
12
    .webhooks()
13
    .update({
14
      filters: ["onMessageAdd", "onMessageUpdate", "onMessageRemove"],
15
      method: "POST",
16
      postWebhookUrl: "https://YOUR_APPLICATION.com/webhook",
17
      preWebhookUrl: "https://YOUR_APPLICATION.com/webhook",
18
      target: "webhook",
19
    });
20

21
  console.log(webhook.accountSid);
22
}
23

24
updateConfigurationWebhook();

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

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const 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
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function listConversationScopedWebhook() {
11
  const webhooks = await client.conversations.v1
12
    .conversations("ConversationSid")
13
    .webhooks.list({ limit: 20 });
14

15
  webhooks.forEach((w) => console.log(w.sid));
16
}
17

18
listConversationScopedWebhook();

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

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const 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
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function fetchConversationScopedWebhook() {
11
  const webhook = await client.conversations.v1
12
    .conversations("ConversationSid")
13
    .webhooks("WHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
14
    .fetch();
15

16
  console.log(webhook.sid);
17
}
18

19
fetchConversationScopedWebhook();

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

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const 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
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function createConversationScopedWebhook() {
11
  const webhook = await client.conversations.v1
12
    .conversations("ConversationSid")
13
    .webhooks.create({
14
      "configuration.filters": ["onMessageAdded", "onMessageUpdated"],
15
      "configuration.url": "https://YOUR_APPLICATION.com/webhook",
16
      target: "webhook",
17
    });
18

19
  console.log(webhook.sid);
20
}
21

22
createConversationScopedWebhook();

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

When Twilio makes an HTTP request to your server, it includes information about the action that triggered the webhook call to your web application. Each action has its own event type.

In addition to the event-specific parameters, each request also contains the following parameters and information:

Note: Each HTTP request is issued with the Content-Type header application/x-www-urlencoded.

You may modify the FriendlyName of this conversation by replying to this webhook with a JSON object that contains the new friendly name.

Note: MessagingBinding.ProxyAddress and MessagingBinding.Address attributes are null if the Conversation is created from the REST API and there are no participants yet. Note: When auto-creating Group MMS Conversation, MessagingBinding.Address is shown as a list of Addresses.

You may modify the FriendlyName of this conversation by replying to this webhook with a JSON object that contains the new friendly name.

Your application may modify the Body and Author parameters in the pre-event webhook. To update these parameters, reply to the webhook with a JSON object that contains the relevant keys and values.

Your application may modify the Body and Authorparameters in the pre-event webhook. To update these parameters, reply to the webhook with a JSON object that contains the relevant keys and values.

Note: A Conversation Participant has either the Identity (and MessagingBinding ProjectedAddress for GroupMMS Participant) or MessagingBinding ProxyAddress and Address attributes filled in. In case the added participant is SMS or WhatsApp, Identity is null and both addresses are supplied. If the added participant is Chat-only, the Identity value is provided, and both MessagingBinding addresses (MessagingBinding ProxyAddress and Address) are null.

Note: A Conversation Participant has either the Identity (and MessagingBinding ProjectedAddress for GroupMMS Participant) or MessagingBinding ProxyAddress and Address attributes filled in. In case the added participant is SMS or WhatsApp, Identity is null and both addresses are supplied. If the added participant is Chat-only, the Identity value is provided, and both MessagingBinding addresses (MessagingBinding ProxyAddress and Address) are null.

Note: A Conversation Participant has either the Identity (and MessagingBinding ProjectedAddress for GroupMMS Participant) or MessagingBinding ProxyAddress and Address attributes filled in. In case the added participant is SMS or WhatsApp, Identity is null and both addresses are supplied. If the added participant is Chat-only, the Identity value is provided, and both MessagingBinding addresses (MessagingBinding ProxyAddress and Address) are null.

You may modify the FriendlyName of this conversation by replying to this webhook with a JSON object that contains the new friendly name.

Note: A Conversation Participant has either the Identity (and MessagingBinding ProjectedAddress for GroupMMS Participant) or MessagingBinding ProxyAddress and Address attributes filled in. In case the added participant is SMS or WhatsApp, Identity is null and both addresses are supplied. If the added participant is Chat-only, the Identity value is provided, and both MessagingBinding addresses (MessagingBinding ProxyAddress and Address) are null.

Note: A Conversation Participant has either the Identity (and MessagingBinding ProjectedAddress for GroupMMS Participant) or MessagingBinding ProxyAddress and Address attributes filled in. In case the added participant is SMS or WhatsApp, Identity is null and both addresses are supplied. If the added participant is Chat-only, the Identity value is provided, and both MessagingBinding addresses (MessagingBinding ProxyAddress and Address) are null.

Note: A Conversation Participant has either the Identity (and MessagingBinding ProjectedAddress for GroupMMS Participant) or MessagingBinding ProxyAddress and Address attributes filled in. In case the added participant is SMS or WhatsApp, Identity is null and both addresses are supplied. If the added participant is Chat-only, the Identity value is provided, and both MessagingBinding addresses (MessagingBinding ProxyAddress and Address) are null.

Pass-through metadata from the OTT channel. Currently, only supported for Google Business Messages. The channel key (gbm) is always available, but the values passed inside are set by Google and are subject to change.

1
"ChannelMetadata": "{
2
    \"gbm\": {
3
        \"context\": {
4
            \"placeId\": \"ChIJU6DUSUUVkCQRxl6dlKFV8ok\",
5
            \"entryPoint\": \"PLACESHEET\",
6
            \"userInfo\": { \"displayName\": \"Sample Name\", \"userDeviceLocale\": \"en-US\" },
7
            \"resolvedLocale\": \"en\"
8
        }
9
    }
10
}"