Programmable Chat has been deprecated and is no longer supported. Instead, we'll be focusing on the next generation of chat: Twilio Conversations. Find out more about the EOL process here.
If you're starting a new project, please visit the Conversations Docs to begin. If you've already built on Programmable Chat, please visit our Migration Guide to learn about how to switch.
This is reference documentation for the v1 REST API, which has been deprecated. You should use the current v2 REST API.
A Service is the top-level scope of all other resources in the Programmable Chat REST API. It owns Channels, Users, Messages, Credentials, and all other data for a Chat implementation. Services allow the developer to:
A Service will also send HTTP requests to URLs configured by the developer when interesting events happen. Check out the webhook reference to see what events you can subscribe to in your Service.
You can manage your Programmable Chat Services using your Twilio console when logged in to the console.
Each service has these properties:
The unique string that we created to identify the Service resource.
^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34The SID of the Account that created the Service resource.
^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34The date and time in GMT when the resource was created specified in RFC 2822 format.
The date and time in GMT when the resource was last updated specified in RFC 2822 format.
The service role assigned to users when they are added to the service. See the Roles endpoint for more details.
^RL[0-9a-fA-F]{32}$Min length: 34Max length: 34The channel role assigned to users when they are added to a channel. See the Roles endpoint for more details.
^RL[0-9a-fA-F]{32}$Min length: 34Max length: 34The channel role assigned to a channel creator when they join a new channel. See the Roles endpoint for more details.
^RL[0-9a-fA-F]{32}$Min length: 34Max length: 34Whether the Message Consumption Horizon feature is enabled. The default is true.
Whether the Reachability Indicator is enabled for this Service instance. The default is false.
How long in seconds after a started typing event until clients should assume that user is no longer typing, even if no ended typing message was received. The default is 5 seconds.
0DEPRECATED. The interval in seconds between consumption reports submission batches from client endpoints.
0An object that describes the limits of the service instance. The limits object contains channel_members to describe the members/channel limit and user_channels to describe the channels/user limit. channel_members can be 1,000 or less, with a default of 250. user_channels can be 1,000 or less, with a default value of 100.
An object that contains information about the webhooks configured for this service.
The URL for pre-event webhooks, which are called by using the webhook_method. See Webhook Events for more details.
The URL for post-event webhooks, which are called by using the webhook_method. See Webhook Events for more details.
The HTTP method to use for calls to the pre_webhook_url and post_webhook_url webhooks. Can be: POST or GET and the default is POST. See Webhook Events for more details.
The list of WebHook events that are enabled for this Service instance. See Webhook Events for more details.
The notification configuration for the Service instance. See Push Notification Configuration for more information.
1GET /Services2
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 listService() {11const services = await client.chat.v1.services.list({ limit: 20 });1213services.forEach((s) => console.log(s.sid));14}1516listService();
1{2"meta": {3"first_page_url": "https://chat.twilio.com/v1/Services?PageSize=50&Page=0",4"key": "services",5"next_page_url": null,6"page": 0,7"page_size": 50,8"previous_page_url": null,9"url": "https://chat.twilio.com/v1/Services?PageSize=50&Page=0"10},11"services": []12}
1`POST /Services`2
application/x-www-form-urlencodedA descriptive string that you create to describe the resource. It can be up to 64 characters long.
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 createService() {11const service = await client.chat.v1.services.create({12friendlyName: "FRIENDLY_NAME",13});1415console.log(service.sid);16}1718createService();
1{2"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"consumption_report_interval": 100,4"date_created": "2015-07-30T20:00:00Z",5"date_updated": "2015-07-30T20:00:00Z",6"default_channel_creator_role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",7"default_channel_role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",8"default_service_role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",9"friendly_name": "FRIENDLY_NAME",10"limits": {11"channel_members": 100,12"user_channels": 25013},14"links": {15"channels": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels",16"users": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Users",17"roles": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Roles"18},19"notifications": {},20"post_webhook_url": "post_webhook_url",21"pre_webhook_url": "pre_webhook_url",22"reachability_enabled": false,23"read_status_enabled": false,24"sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",25"typing_indicator_timeout": 100,26"url": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",27"webhook_filters": [28"webhook_filters"29],30"webhook_method": "webhook_method",31"webhooks": {}32}
1`GET /Services/ISxxx`2
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 fetchService() {11const service = await client.chat.v112.services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")13.fetch();1415console.log(service.sid);16}1718fetchService();
1{2"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"consumption_report_interval": 100,4"date_created": "2015-07-30T20:00:00Z",5"date_updated": "2015-07-30T20:00:00Z",6"default_channel_creator_role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",7"default_channel_role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",8"default_service_role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",9"friendly_name": "friendly_name",10"limits": {11"channel_members": 100,12"user_channels": 25013},14"links": {15"channels": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels",16"users": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Users",17"roles": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Roles"18},19"notifications": {},20"post_webhook_url": "post_webhook_url",21"pre_webhook_url": "pre_webhook_url",22"reachability_enabled": false,23"read_status_enabled": false,24"sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",25"typing_indicator_timeout": 100,26"url": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",27"webhook_filters": [28"webhook_filters"29],30"webhook_method": "webhook_method",31"webhooks": {}32}
1`POST /Services/ISxxx`2
The Twilio-provided string that uniquely identifies the Service resource to update.
^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34application/x-www-form-urlencodedA descriptive string that you create to describe the resource. It can be up to 64 characters long.
The service role assigned to users when they are added to the service. See the Roles endpoint for more details.
^RL[0-9a-fA-F]{32}$Min length: 34Max length: 34The channel role assigned to users when they are added to a channel. See the Roles endpoint for more details.
^RL[0-9a-fA-F]{32}$Min length: 34Max length: 34The channel role assigned to a channel creator when they join a new channel. See the Roles endpoint for more details.
^RL[0-9a-fA-F]{32}$Min length: 34Max length: 34Whether to enable the Message Consumption Horizon feature. The default is true.
Whether to enable the Reachability Indicator for this Service instance. The default is false.
How long in seconds after a started typing event until clients should assume that user is no longer typing, even if no ended typing message was received. The default is 5 seconds.
DEPRECATED. The interval in seconds between consumption reports submission batches from client endpoints.
Whether to send a notification when a new message is added to a channel. Can be: true or false and the default is false.
The template to use to create the notification text displayed when a new message is added to a channel and notifications.new_message.enabled is true.
Whether to send a notification when a member is added to a channel. Can be: true or false and the default is false.
The template to use to create the notification text displayed when a member is added to a channel and notifications.added_to_channel.enabled is true.
Whether to send a notification to a user when they are removed from a channel. Can be: true or false and the default is false.
The template to use to create the notification text displayed to a user when they are removed from a channel and notifications.removed_from_channel.enabled is true.
Whether to send a notification when a user is invited to a channel. Can be: true or false and the default is false.
The template to use to create the notification text displayed when a user is invited to a channel and notifications.invited_to_channel.enabled is true.
The URL for pre-event webhooks, which are called by using the webhook_method. See Webhook Events for more details.
The URL for post-event webhooks, which are called by using the webhook_method. See Webhook Events for more details.
The HTTP method to use for calls to the pre_webhook_url and post_webhook_url webhooks. Can be: POST or GET and the default is POST. See Webhook Events for more details.
GETPOSTThe list of WebHook events that are enabled for this Service instance. See Webhook Events for more details.
The URL of the webhook to call in response to the on_message_send event using the webhooks.on_message_send.method HTTP method.
The HTTP method to use when calling the webhooks.on_message_send.url.
GETPOSTThe URL of the webhook to call in response to the on_message_update event using the webhooks.on_message_update.method HTTP method.
The HTTP method to use when calling the webhooks.on_message_update.url.
GETPOSTThe URL of the webhook to call in response to the on_message_remove event using the webhooks.on_message_remove.method HTTP method.
The HTTP method to use when calling the webhooks.on_message_remove.url.
GETPOSTThe URL of the webhook to call in response to the on_channel_add event using the webhooks.on_channel_add.method HTTP method.
The HTTP method to use when calling the webhooks.on_channel_add.url.
GETPOSTThe URL of the webhook to call in response to the on_channel_destroy event using the webhooks.on_channel_destroy.method HTTP method.
The HTTP method to use when calling the webhooks.on_channel_destroy.url.
GETPOSTThe URL of the webhook to call in response to the on_channel_update event using the webhooks.on_channel_update.method HTTP method.
The HTTP method to use when calling the webhooks.on_channel_update.url.
GETPOSTThe URL of the webhook to call in response to the on_member_add event using the webhooks.on_member_add.method HTTP method.
The HTTP method to use when calling the webhooks.on_member_add.url.
GETPOSTThe URL of the webhook to call in response to the on_member_remove event using the webhooks.on_member_remove.method HTTP method.
The HTTP method to use when calling the webhooks.on_member_remove.url.
GETPOSTThe URL of the webhook to call in response to the on_message_sent event using the webhooks.on_message_sent.method HTTP method.
The URL of the webhook to call in response to the on_message_sent event`.
GETPOSTThe URL of the webhook to call in response to the on_message_updated event using the webhooks.on_message_updated.method HTTP method.
The HTTP method to use when calling the webhooks.on_message_updated.url.
GETPOSTThe URL of the webhook to call in response to the on_message_removed event using the webhooks.on_message_removed.method HTTP method.
The HTTP method to use when calling the webhooks.on_message_removed.url.
GETPOSTThe URL of the webhook to call in response to the on_channel_added event using the webhooks.on_channel_added.method HTTP method.
The URL of the webhook to call in response to the on_channel_added event`.
GETPOSTThe URL of the webhook to call in response to the on_channel_added event using the webhooks.on_channel_destroyed.method HTTP method.
The HTTP method to use when calling the webhooks.on_channel_destroyed.url.
GETPOSTThe URL of the webhook to call in response to the on_channel_updated event using the webhooks.on_channel_updated.method HTTP method.
The HTTP method to use when calling the webhooks.on_channel_updated.url.
GETPOSTThe URL of the webhook to call in response to the on_channel_updated event using the webhooks.on_channel_updated.method HTTP method.
The HTTP method to use when calling the webhooks.on_channel_updated.url.
GETPOSTThe URL of the webhook to call in response to the on_member_removed event using the webhooks.on_member_removed.method HTTP method.
The HTTP method to use when calling the webhooks.on_member_removed.url.
GETPOSTThe maximum number of Members that can be added to Channels within this Service. Can be up to 1,000.
The maximum number of Channels Users can be a Member of within this Service. Can be up to 1,000.
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 updateService() {11const service = await client.chat.v112.services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.update({ friendlyName: "NEW_FRIENDLY_NAME" });1415console.log(service.sid);16}1718updateService();
1{2"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"consumption_report_interval": 100,4"date_created": "2015-07-30T20:00:00Z",5"date_updated": "2015-07-30T20:00:00Z",6"default_channel_creator_role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",7"default_channel_role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",8"default_service_role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",9"friendly_name": "NEW_FRIENDLY_NAME",10"limits": {11"channel_members": 500,12"user_channels": 60013},14"links": {15"channels": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels",16"users": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Users",17"roles": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Roles"18},19"notifications": {20"added_to_channel": {21"enabled": false,22"template": "notifications.added_to_channel.template"23},24"invited_to_channel": {25"enabled": false,26"template": "notifications.invited_to_channel.template"27},28"new_message": {29"enabled": false,30"template": "notifications.new_message.template"31},32"removed_from_channel": {33"enabled": false,34"template": "notifications.removed_from_channel.template"35}36},37"post_webhook_url": "post_webhook_url",38"pre_webhook_url": "pre_webhook_url",39"reachability_enabled": false,40"read_status_enabled": false,41"sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",42"typing_indicator_timeout": 100,43"url": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",44"webhook_filters": [45"webhook_filters"46],47"webhook_method": "webhook_method",48"webhooks": {49"on_channel_add": {50"format": "webhooks.on_channel_add.format",51"method": "webhooks.on_channel_add.method",52"url": "webhooks.on_channel_add.url"53},54"on_channel_added": {55"format": "webhooks.on_channel_added.format",56"method": "webhooks.on_channel_added.method",57"url": "webhooks.on_channel_added.url"58},59"on_channel_destroy": {60"format": "webhooks.on_channel_destroy.format",61"method": "webhooks.on_channel_destroy.method",62"url": "webhooks.on_channel_destroy.url"63},64"on_channel_destroyed": {65"format": "webhooks.on_channel_destroyed.format",66"method": "webhooks.on_channel_destroyed.method",67"url": "webhooks.on_channel_destroyed.url"68},69"on_channel_update": {70"format": "webhooks.on_channel_update.format",71"method": "webhooks.on_channel_update.method",72"url": "webhooks.on_channel_update.url"73},74"on_channel_updated": {75"format": "webhooks.on_channel_updated.format",76"method": "webhooks.on_channel_updated.method",77"url": "webhooks.on_channel_updated.url"78},79"on_member_add": {80"format": "webhooks.on_member_add.format",81"method": "webhooks.on_member_add.method",82"url": "webhooks.on_member_add.url"83},84"on_member_added": {85"format": "webhooks.on_member_added.format",86"method": "webhooks.on_member_added.method",87"url": "webhooks.on_member_added.url"88},89"on_member_remove": {90"format": "webhooks.on_member_remove.format",91"method": "webhooks.on_member_remove.method",92"url": "webhooks.on_member_remove.url"93},94"on_member_removed": {95"format": "webhooks.on_member_removed.format",96"method": "webhooks.on_member_removed.method",97"url": "webhooks.on_member_removed.url"98},99"on_message_remove": {100"format": "webhooks.on_message_remove.format",101"method": "webhooks.on_message_remove.method",102"url": "webhooks.on_message_remove.url"103},104"on_message_removed": {105"format": "webhooks.on_message_removed.format",106"method": "webhooks.on_message_removed.method",107"url": "webhooks.on_message_removed.url"108},109"on_message_send": {110"format": "webhooks.on_message_send.format",111"method": "webhooks.on_message_send.method",112"url": "webhooks.on_message_send.url"113},114"on_message_sent": {115"format": "webhooks.on_message_sent.format",116"method": "webhooks.on_message_sent.method",117"url": "webhooks.on_message_sent.url"118},119"on_message_update": {120"format": "webhooks.on_message_update.format",121"method": "webhooks.on_message_update.method",122"url": "webhooks.on_message_update.url"123},124"on_message_updated": {125"format": "webhooks.on_message_updated.format",126"method": "webhooks.on_message_updated.method",127"url": "webhooks.on_message_updated.url"128}129}130}
1`DELETE /Services/ISxxx`2
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 deleteService() {11await client.chat.v1.services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX").remove();12}1314deleteService();