Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Chat Service Resource


(error)

Danger

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(link takes you to an external page).

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.

A Service is the top-level scope of all other resources in the Programmable Chat REST API. All other Programmable Chat resources, such as Channels, Users, Messages, and Credentials belong to a specific Service.

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

A Service can also send HTTPS requests(link takes you to an external page) to URLs that you define to let you know of specific events. See what events you can subscribe to in our webhook reference.


Twilio Console

twilio-console page anchor

You can also manage your Programmable Chat Services from your Twilio console when you are logged in.


The Service resource contains these properties.

Resource properties
sidtype: SID<IS>Not PII

The unique string that we created to identify the Service resource.


account_sidtype: SID<AC>Not PII

The SID of the Account(link takes you to an external page) that created the Service resource.


friendly_nametype: stringPII MTL: 30 days

The string that you assigned to describe the resource.


date_createdtype: string<DATE TIME>Not PII

The date and time in GMT when the resource was created specified in ISO 8601(link takes you to an external page) format.


date_updatedtype: string<DATE TIME>Not PII

The date and time in GMT when the resource was last updated specified in ISO 8601(link takes you to an external page) format.


default_service_role_sidtype: SID<RL>Not PII

The service role assigned to users when they are added to the service. See the Role resource(link takes you to an external page) for more info about roles.


default_channel_role_sidtype: SID<RL>Not PII

The channel role assigned to users when they are added to a channel. See the Role resource(link takes you to an external page) for more info about roles.


default_channel_creator_role_sidtype: SID<RL>Not PII

The channel role assigned to a channel creator when they join a new channel. See the Role resource(link takes you to an external page) for more info about roles.


read_status_enabledtype: booleanNot PII

Whether the Message Consumption Horizon(link takes you to an external page) feature is enabled. The default is true.


reachability_enabledtype: booleanNot PII

Whether the Reachability Indicator(link takes you to an external page) is enabled for this Service instance. The default is false.


typing_indicator_timeouttype: integerNot PII

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.


consumption_report_intervaltype: integerNot PII

DEPRECATED. The interval in seconds between consumption reports submission batches from client endpoints.


limitstype: objectNot PII

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


pre_webhook_urltype: stringNot PII

The URL for pre-event webhooks, which are called by using the webhook_method. See Webhook Events(link takes you to an external page) for more details.


post_webhook_urltype: stringNot PII

The URL for post-event webhooks, which are called by using the webhook_method. See Webhook Events(link takes you to an external page) for more details.


webhook_methodtype: stringNot PII

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(link takes you to an external page) for more details.


webhook_filterstype: string[]Not PII

The list of webhook events that are enabled for this Service instance. See Webhook Events(link takes you to an external page) for more details.


pre_webhook_retry_counttype: integerNot PII

The number of times to retry a call to the pre_webhook_url if the request times out (after 5 seconds) or it receives a 429, 503, or 504 HTTP response. Default retry count is 0 times, which means the call won't be retried.


post_webhook_retry_counttype: integerNot PII

The number of times to retry a call to the post_webhook_url if the request times out (after 5 seconds) or it receives a 429, 503, or 504 HTTP response. The default is 0, which means the call won't be retried.


notificationstype: objectNot PII

The notification configuration for the Service instance. See Push Notification Configuration(link takes you to an external page) for more info.


mediatype: objectNot PII

An object that describes the properties of media that the service supports. The object contains the size_limit_mb property, which describes the size of the largest media file in MB; and the compatibility_message property, which contains the message text to send when a media message does not have any text.


urltype: string<URI>Not PII

The absolute URL of the Service resource.



Create a Service resource

create-a-service-resource page anchor
POST https://chat.twilio.com/v2/Services

Parameters

create-parameters page anchor
Request body parameters
FriendlyNametype: stringPII MTL: 30 days
Required

A descriptive string that you create to describe the new resource.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.chat.v2.services.create({friendlyName: 'friendly_name'})
_10
.then(service => console.log(service.sid));

Output

_38
{
_38
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_38
"consumption_report_interval": 100,
_38
"date_created": "2015-07-30T20:00:00Z",
_38
"date_updated": "2015-07-30T20:00:00Z",
_38
"default_channel_creator_role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_38
"default_channel_role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_38
"default_service_role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_38
"friendly_name": "friendly_name",
_38
"limits": {
_38
"channel_members": 100,
_38
"user_channels": 250
_38
},
_38
"links": {
_38
"channels": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels",
_38
"users": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Users",
_38
"roles": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Roles",
_38
"bindings": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Bindings"
_38
},
_38
"notifications": {},
_38
"post_webhook_url": "post_webhook_url",
_38
"pre_webhook_url": "pre_webhook_url",
_38
"pre_webhook_retry_count": 2,
_38
"post_webhook_retry_count": 3,
_38
"reachability_enabled": false,
_38
"read_status_enabled": false,
_38
"sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_38
"typing_indicator_timeout": 100,
_38
"url": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_38
"webhook_filters": [
_38
"webhook_filters"
_38
],
_38
"webhook_method": "webhook_method",
_38
"media": {
_38
"size_limit_mb": 150,
_38
"compatibility_message": "media compatibility message"
_38
}
_38
}


Fetch a Service resource

fetch-a-service-resource page anchor
GET https://chat.twilio.com/v2/Services/{Sid}

URI parameters
Sidtype: SID<IS>Not PII
Path Parameter

The SID of the Service resource to fetch.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.chat.v2.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.fetch()
_10
.then(service => console.log(service.friendlyName));

Output

_38
{
_38
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_38
"consumption_report_interval": 100,
_38
"date_created": "2015-07-30T20:00:00Z",
_38
"date_updated": "2015-07-30T20:00:00Z",
_38
"default_channel_creator_role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_38
"default_channel_role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_38
"default_service_role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_38
"friendly_name": "friendly_name",
_38
"limits": {
_38
"channel_members": 100,
_38
"user_channels": 250
_38
},
_38
"links": {
_38
"channels": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels",
_38
"users": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Users",
_38
"roles": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Roles",
_38
"bindings": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Bindings"
_38
},
_38
"notifications": {},
_38
"post_webhook_url": "post_webhook_url",
_38
"pre_webhook_url": "pre_webhook_url",
_38
"pre_webhook_retry_count": 2,
_38
"post_webhook_retry_count": 3,
_38
"reachability_enabled": false,
_38
"read_status_enabled": false,
_38
"sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_38
"typing_indicator_timeout": 100,
_38
"url": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_38
"webhook_filters": [
_38
"webhook_filters"
_38
],
_38
"webhook_method": "webhook_method",
_38
"media": {
_38
"size_limit_mb": 150,
_38
"compatibility_message": "media compatibility message"
_38
}
_38
}


Read multiple Service resources

read-multiple-service-resources page anchor
GET https://chat.twilio.com/v2/Services

URI parameters
PageSizetype: integerNot PII
Query Parameter

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


Pagetype: integerNot PII
Query Parameter

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


PageTokentype: stringNot PII
Query Parameter

The page token. This is provided by the API.

Read multiple Service resources

read-multiple-service-resources-1 page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.chat.v2.services.list({limit: 20})
_10
.then(services => services.forEach(s => console.log(s.sid)));

Output

_51
{
_51
"meta": {
_51
"first_page_url": "https://chat.twilio.com/v2/Services?PageSize=50&Page=0",
_51
"key": "services",
_51
"next_page_url": "https://chat.twilio.com/v2/Services?PageSize=50&Page=1",
_51
"page": 0,
_51
"page_size": 50,
_51
"previous_page_url": "https://chat.twilio.com/v2/Services?PageSize=50&Page=0",
_51
"url": "https://chat.twilio.com/v2/Services?PageSize=50&Page=0"
_51
},
_51
"services": [
_51
{
_51
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51
"consumption_report_interval": 100,
_51
"date_created": "2015-07-30T20:00:00Z",
_51
"date_updated": "2015-07-30T20:00:00Z",
_51
"default_channel_creator_role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51
"default_channel_role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51
"default_service_role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51
"friendly_name": "friendly_name",
_51
"limits": {
_51
"channel_members": 100,
_51
"user_channels": 250
_51
},
_51
"links": {
_51
"channels": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels",
_51
"users": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Users",
_51
"roles": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Roles",
_51
"bindings": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Bindings"
_51
},
_51
"notifications": {},
_51
"post_webhook_url": "post_webhook_url",
_51
"pre_webhook_url": "pre_webhook_url",
_51
"pre_webhook_retry_count": 2,
_51
"post_webhook_retry_count": 3,
_51
"reachability_enabled": false,
_51
"read_status_enabled": false,
_51
"sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51
"typing_indicator_timeout": 100,
_51
"url": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51
"webhook_filters": [
_51
"webhook_filters"
_51
],
_51
"webhook_method": "webhook_method",
_51
"media": {
_51
"size_limit_mb": 150,
_51
"compatibility_message": "media compatibility message"
_51
}
_51
}
_51
]
_51
}


Update a Service resource

update-a-service-resource page anchor
POST https://chat.twilio.com/v2/Services/{Sid}

URI parameters
Sidtype: SID<IS>Not PII
Path Parameter

The SID of the Service resource to update.


Request body parameters
FriendlyNametype: stringPII MTL: 30 days

A descriptive string that you create to describe the resource.


DefaultServiceRoleSidtype: SID<RL>Not PII

The service role assigned to users when they are added to the service. See the Role resource(link takes you to an external page) for more info about roles.


DefaultChannelRoleSidtype: SID<RL>Not PII

The channel role assigned to users when they are added to a channel. See the Role resource(link takes you to an external page) for more info about roles.


DefaultChannelCreatorRoleSidtype: SID<RL>Not PII

The channel role assigned to a channel creator when they join a new channel. See the Role resource(link takes you to an external page) for more info about roles.


ReadStatusEnabledtype: booleanNot PII

Whether to enable the Message Consumption Horizon(link takes you to an external page) feature. The default is true.


ReachabilityEnabledtype: booleanNot PII

Whether to enable the Reachability Indicator(link takes you to an external page) for this Service instance. The default is false.


TypingIndicatorTimeouttype: integerNot PII

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.


ConsumptionReportIntervaltype: integerNot PII

DEPRECATED. The interval in seconds between consumption reports submission batches from client endpoints.


Notifications.NewMessage.Enabledtype: booleanNot PII

Whether to send a notification when a new message is added to a channel. The default is false.


Notifications.NewMessage.Templatetype: stringNot PII

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.


Notifications.NewMessage.Soundtype: stringNot PII

The name of the sound to play when a new message is added to a channel and notifications.new_message.enabled is true.


Notifications.NewMessage.BadgeCountEnabledtype: booleanNot PII

Whether the new message badge is enabled. The default is false.


Notifications.AddedToChannel.Enabledtype: booleanNot PII

Whether to send a notification when a member is added to a channel. The default is false.


Notifications.AddedToChannel.Templatetype: stringNot PII

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.


Notifications.AddedToChannel.Soundtype: stringNot PII

The name of the sound to play when a member is added to a channel and notifications.added_to_channel.enabled is true.


Notifications.RemovedFromChannel.Enabledtype: booleanNot PII

Whether to send a notification to a user when they are removed from a channel. The default is false.


Notifications.RemovedFromChannel.Templatetype: stringNot PII

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.


Notifications.RemovedFromChannel.Soundtype: stringNot PII

The name of the sound to play to a user when they are removed from a channel and notifications.removed_from_channel.enabled is true.


Notifications.InvitedToChannel.Enabledtype: booleanNot PII

Whether to send a notification when a user is invited to a channel. The default is false.


Notifications.InvitedToChannel.Templatetype: stringNot PII

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.


Notifications.InvitedToChannel.Soundtype: stringNot PII

The name of the sound to play when a user is invited to a channel and notifications.invited_to_channel.enabled is true.


PreWebhookUrltype: string<URI>Not PII

The URL for pre-event webhooks, which are called by using the webhook_method. See Webhook Events(link takes you to an external page) for more details.


PostWebhookUrltype: string<URI>Not PII

The URL for post-event webhooks, which are called by using the webhook_method. See Webhook Events(link takes you to an external page) for more details.


WebhookMethodtype: enum<HTTP METHOD>Not PII

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(link takes you to an external page) for more details.

Possible values:
HEADGETPOSTPATCHPUTDELETE

WebhookFilterstype: string[]Not PII

The list of webhook events that are enabled for this Service instance. See Webhook Events(link takes you to an external page) for more details.


Limits.ChannelMemberstype: integerNot PII

The maximum number of Members that can be added to Channels within this Service. Can be up to 1,000.


Limits.UserChannelstype: integerNot PII

The maximum number of Channels Users can be a Member of within this Service. Can be up to 1,000.


Media.CompatibilityMessagetype: stringNot PII

The message to send when a media message has no text. Can be used as placeholder message.


PreWebhookRetryCounttype: integerNot PII

The number of times to retry a call to the pre_webhook_url if the request times out (after 5 seconds) or it receives a 429, 503, or 504 HTTP response. Default retry count is 0 times, which means the call won't be retried.


PostWebhookRetryCounttype: integerNot PII

The number of times to retry a call to the post_webhook_url if the request times out (after 5 seconds) or it receives a 429, 503, or 504 HTTP response. The default is 0, which means the call won't be retried.


Notifications.LogEnabledtype: booleanNot PII

Whether to log notifications. The default is false.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.chat.v2.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.update({friendlyName: 'friendly_name'})
_10
.then(service => console.log(service.friendlyName));

Output

_57
{
_57
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_57
"consumption_report_interval": 100,
_57
"date_created": "2015-07-30T20:00:00Z",
_57
"date_updated": "2015-07-30T20:00:00Z",
_57
"default_channel_creator_role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_57
"default_channel_role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_57
"default_service_role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_57
"friendly_name": "friendly_name",
_57
"limits": {
_57
"channel_members": 500,
_57
"user_channels": 600
_57
},
_57
"links": {
_57
"channels": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels",
_57
"users": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Users",
_57
"roles": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Roles",
_57
"bindings": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Bindings"
_57
},
_57
"notifications": {
_57
"log_enabled": true,
_57
"added_to_channel": {
_57
"enabled": false,
_57
"template": "notifications.added_to_channel.template"
_57
},
_57
"invited_to_channel": {
_57
"enabled": false,
_57
"template": "notifications.invited_to_channel.template"
_57
},
_57
"new_message": {
_57
"enabled": false,
_57
"template": "notifications.new_message.template",
_57
"badge_count_enabled": true
_57
},
_57
"removed_from_channel": {
_57
"enabled": false,
_57
"template": "notifications.removed_from_channel.template"
_57
}
_57
},
_57
"post_webhook_url": "post_webhook_url",
_57
"pre_webhook_url": "pre_webhook_url",
_57
"pre_webhook_retry_count": 2,
_57
"post_webhook_retry_count": 3,
_57
"reachability_enabled": false,
_57
"read_status_enabled": false,
_57
"sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_57
"typing_indicator_timeout": 100,
_57
"url": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_57
"webhook_filters": [
_57
"webhook_filters"
_57
],
_57
"webhook_method": "webhook_method",
_57
"media": {
_57
"size_limit_mb": 150,
_57
"compatibility_message": "new media compatibility message"
_57
}
_57
}


Delete a Service resource

delete-a-service-resource page anchor
DELETE https://chat.twilio.com/v2/Services/{Sid}

URI parameters
Sidtype: SID<IS>Not PII
Path Parameter

The SID of the Service resource to delete.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.chat.v2.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX').remove();


Rate this page: