Per-Service Webhook Resource
The Per-Service Webhook resource allows you to control the effects of webhooks in a particular Conversation Service. The webhooks will only fire for activity at the service-level.
Services allow you to:
- Create multiple, distinct environments (such as dev, stage, and prod) under a single Twilio account
- Scope access to resources through both the REST and client APIs
- Configure different service instances with specific behaviors
Every service can have unique webhook targets. This means you can include different metadata in the URLs or even trigger different behavior for different services.
Webhook targets for the Service Instance (the URL that Twilio will invoke) are configured in the Twilio Console.
If configured, service-scoped webhooks will override your global webhook settings such that only the service-scoped hooks will fire. This applies only to the services where service-level hooks are configured. See Conversations Webhooksfor more information.
The unique ID of the Account responsible for this service.
^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34The unique ID of the Conversation Service this conversation belongs to.
^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34The absolute url the pre-event webhook request should be sent to.
The absolute url the post-event webhook request should be sent to.
The list of events that your configured webhook targets will receive. Events not configured here will not fire. Possible values are onParticipantAdd, onParticipantAdded, onDeliveryUpdated, onConversationUpdated, onConversationRemove, onParticipantRemove, onConversationUpdate, onMessageAdd, onMessageRemoved, onParticipantUpdated, onConversationAdded, onMessageAdded, onConversationAdd, onConversationRemoved, onParticipantUpdate, onMessageRemove, onMessageUpdated, onParticipantRemoved, onMessageUpdate or onConversationStateUpdated.
The HTTP method to be used when sending a webhook request. One of GET or POST.
GETPOSTAn absolute API resource URL for this webhook.
GET https://conversations.twilio.com/v1/Services/{ChatServiceSid}/Configuration/Webhooks
The unique ID of the Conversation Service this conversation belongs to.
^IS[0-9a-fA-F]{32}$Min length: 34Max length: 341// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function fetchServiceWebhookConfiguration() {11const webhook = await client.conversations.v112.services("ISXXXXXXXXXXXXXXXXXXXXXX")13.configuration.webhooks()14.fetch();1516console.log(webhook.accountSid);17}1819fetchServiceWebhookConfiguration();
Response
1{2"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"chat_service_sid": "ISXXXXXXXXXXXXXXXXXXXXXX",4"pre_webhook_url": "https://www.example.com/pre",5"post_webhook_url": "https://www.example.com/post",6"filters": [7"onMessageRemove",8"onParticipantAdd"9],10"method": "POST",11"url": "https://conversations.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Configuration/Webhooks"12}
POST https://conversations.twilio.com/v1/Services/{ChatServiceSid}/Configuration/Webhooks
The unique ID of the Conversation Service this conversation belongs to.
^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34application/x-www-form-urlencodedThe absolute url the pre-event webhook request should be sent to.
The absolute url the post-event webhook request should be sent to.
The list of events that your configured webhook targets will receive. Events not configured here will not fire. Possible values are onParticipantAdd, onParticipantAdded, onDeliveryUpdated, onConversationUpdated, onConversationRemove, onParticipantRemove, onConversationUpdate, onMessageAdd, onMessageRemoved, onParticipantUpdated, onConversationAdded, onMessageAdded, onConversationAdd, onConversationRemoved, onParticipantUpdate, onMessageRemove, onMessageUpdated, onParticipantRemoved, onMessageUpdate or onConversationStateUpdated.
The HTTP method to be used when sending a webhook request. One of GET or POST.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function updateServiceWebhookConfiguration() {11const webhook = await client.conversations.v112.services("ISXXXXXXXXXXXXXXXXXXXXXX")13.configuration.webhooks()14.update({15filters: ["onConversationUpdated", "onMessageRemoved"],16method: "POST",17postWebhookUrl: "https://example.com/archive-every-action",18preWebhookUrl: "https://example.com/filtering-and-permissions",19});2021console.log(webhook.accountSid);22}2324updateServiceWebhookConfiguration();
Response
1{2"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"chat_service_sid": "ISXXXXXXXXXXXXXXXXXXXXXX",4"pre_webhook_url": "https://example.com/filtering-and-permissions",5"post_webhook_url": "https://example.com/archive-every-action",6"filters": [7"onMessageRemoved",8"onParticipantAdded"9],10"method": "POST",11"url": "https://conversations.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Configuration/Webhooks"12}