Chat Service Resource
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.
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 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
You can also manage your Programmable Chat Services from your Twilio console when you are logged in.
Service properties
The Service resource contains these properties.
| Resource Properties in REST API format | |
|---|---|
sid
|
The unique string that we created to identify the Service resource. |
account_sid
|
The SID of the Account that created the Service resource. |
friendly_name
|
The string that you assigned to describe the resource. |
date_created
|
The date and time in GMT when the resource was created specified in ISO 8601 format. |
date_updated
|
The date and time in GMT when the resource was last updated specified in ISO 8601 format. |
default_service_role_sid
|
The service role assigned to users when they are added to the service. See the Role resource for more info about roles. |
default_channel_role_sid
|
The channel role assigned to users when they are added to a channel. See the Role resource for more info about roles. |
default_channel_creator_role_sid
|
The channel role assigned to a channel creator when they join a new channel. See the Role resource for more info about roles. |
read_status_enabled
|
Whether the Message Consumption Horizon feature is enabled. The default is |
reachability_enabled
|
Whether the Reachability Indicator is enabled for this Service instance. The default is |
typing_indicator_timeout
|
How long in seconds after a |
consumption_report_interval
|
DEPRECATED. The interval in seconds between consumption reports submission batches from client endpoints. |
limits
|
An object that describes the limits of the service instance. The |
pre_webhook_url
|
The URL for pre-event webhooks, which are called by using the |
post_webhook_url
|
The URL for post-event webhooks, which are called by using the |
webhook_method
|
The HTTP method to use for calls to the |
webhook_filters
|
The list of webhook events that are enabled for this Service instance. See Webhook Events for more details. |
pre_webhook_retry_count
|
The number of times to retry a call to the |
post_webhook_retry_count
|
The number of times to retry a call to the |
notifications
|
The notification configuration for the Service instance. See Push Notification Configuration for more info. |
media
|
An object that describes the properties of media that the service supports. The object contains the |
url
|
The absolute URL of the Service resource. |
links
|
The absolute URLs of the Service's Channels, Roles, Bindings, and Users. |
Create a Service resource
https://chat.twilio.com/v2/Services
Parameters
| Parameters in REST API format | |
|---|---|
friendly_name
Required
|
A descriptive string that you create to describe the new resource. |
Example 1
Fetch a Service resource
https://chat.twilio.com/v2/Services/{Sid}
Parameters
| Parameters in REST API format | |
|---|---|
sid
Path
|
The SID of the Service resource to fetch. |
Example 1
Read multiple Service resources
https://chat.twilio.com/v2/Services
Example 1
Update a Service resource
https://chat.twilio.com/v2/Services/{Sid}
Parameters
| Parameters in REST API format | |
|---|---|
sid
Path
|
The SID of the Service resource to update. |
friendly_name
Optional
|
A descriptive string that you create to describe the resource. |
default_service_role_sid
Optional
|
The service role assigned to users when they are added to the service. See the Role resource for more info about roles. |
default_channel_role_sid
Optional
|
The channel role assigned to users when they are added to a channel. See the Role resource for more info about roles. |
default_channel_creator_role_sid
Optional
|
The channel role assigned to a channel creator when they join a new channel. See the Role resource for more info about roles. |
read_status_enabled
Optional
|
Whether to enable the Message Consumption Horizon feature. The default is |
reachability_enabled
Optional
|
Whether to enable the Reachability Indicator for this Service instance. The default is |
typing_indicator_timeout
Optional
|
How long in seconds after a |
consumption_report_interval
Optional
|
DEPRECATED. The interval in seconds between consumption reports submission batches from client endpoints. |
notifications.new_message.enabled
Optional
|
Whether to send a notification when a new message is added to a channel. The default is |
notifications.new_message.template
Optional
|
The template to use to create the notification text displayed when a new message is added to a channel and |
notifications.new_message.sound
Optional
|
The name of the sound to play when a new message is added to a channel and |
notifications.new_message.badge_count_enabled
Optional
|
Whether the new message badge is enabled. The default is |
notifications.added_to_channel.enabled
Optional
|
Whether to send a notification when a member is added to a channel. The default is |
notifications.added_to_channel.template
Optional
|
The template to use to create the notification text displayed when a member is added to a channel and |
notifications.added_to_channel.sound
Optional
|
The name of the sound to play when a member is added to a channel and |
notifications.removed_from_channel.enabled
Optional
|
Whether to send a notification to a user when they are removed from a channel. The default is |
notifications.removed_from_channel.template
Optional
|
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.sound
Optional
|
The name of the sound to play to a user when they are removed from a channel and |
notifications.invited_to_channel.enabled
Optional
|
Whether to send a notification when a user is invited to a channel. The default is |
notifications.invited_to_channel.template
Optional
|
The template to use to create the notification text displayed when a user is invited to a channel and |
notifications.invited_to_channel.sound
Optional
|
The name of the sound to play when a user is invited to a channel and |
pre_webhook_url
Optional
|
The URL for pre-event webhooks, which are called by using the |
post_webhook_url
Optional
|
The URL for post-event webhooks, which are called by using the |
webhook_method
Optional
|
The HTTP method to use for calls to the |
webhook_filters
Optional
|
The list of webhook events that are enabled for this Service instance. See Webhook Events for more details. |
limits.channel_members
Optional
|
The maximum number of Members that can be added to Channels within this Service. Can be up to 1,000. |
limits.user_channels
Optional
|
The maximum number of Channels Users can be a Member of within this Service. Can be up to 1,000. |
media.compatibility_message
Optional
|
The message to send when a media message has no text. Can be used as placeholder message. |
pre_webhook_retry_count
Optional
|
The number of times to retry a call to the |
post_webhook_retry_count
Optional
|
The number of times to retry a call to the |
notifications.log_enabled
Optional
|
Whether to log notifications. The default is |
Example 1
Delete a Service resource
https://chat.twilio.com/v2/Services/{Sid}
Parameters
| Parameters in REST API format | |
|---|---|
sid
Path
|
The SID of the Service resource to delete. |
Example 1
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.
