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:
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.
You can also manage your Programmable Chat Services from your Twilio console when you are logged in.
The Service resource contains these properties.
date_created
type: string<date-time>The date and time in GMT when the resource was created specified in ISO 8601 format.
date_updated
type: string<date-time>The date and time in GMT when the resource was last updated specified in ISO 8601 format.
default_service_role_sid
type: SID<RL>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
type: SID<RL>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
type: SID<RL>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
type: booleanWhether the Message Consumption Horizon feature is enabled. The default is true
.
reachability_enabled
type: booleanWhether the Reachability Indicator is enabled for this Service instance. The default is false
.
typing_indicator_timeout
type: integerHow 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_interval
type: integerDEPRECATED. The interval in seconds between consumption reports submission batches from client endpoints.
limits
type: objectAn 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_url
type: stringThe URL for pre-event webhooks, which are called by using the webhook_method
. See Webhook Events for more details.
post_webhook_url
type: stringThe URL for post-event webhooks, which are called by using the webhook_method
. See Webhook Events for more details.
webhook_method
type: stringThe 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.
webhook_filters
type: array[string]The list of webhook events that are enabled for this Service instance. See Webhook Events for more details.
pre_webhook_retry_count
type: integerThe 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_count
type: integerThe 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
type: objectThe notification configuration for the Service instance. See Push Notification Configuration for more info.
media
type: objectAn 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.
POST https://chat.twilio.com/v2/Services
FriendlyName
type: stringRequiredA descriptive string that you create to describe the new resource.
GET https://chat.twilio.com/v2/Services/{Sid}
GET https://chat.twilio.com/v2/Services
PageSize
type: integerHow many resources to return in each list page. The default is 50, and the maximum is 1000.
POST https://chat.twilio.com/v2/Services/{Sid}
FriendlyName
type: stringA descriptive string that you create to describe the resource.
DefaultServiceRoleSid
type: SID<RL>The service role assigned to users when they are added to the service. See the Role resource for more info about roles.
DefaultChannelRoleSid
type: SID<RL>The channel role assigned to users when they are added to a channel. See the Role resource for more info about roles.
DefaultChannelCreatorRoleSid
type: SID<RL>The channel role assigned to a channel creator when they join a new channel. See the Role resource for more info about roles.
ReadStatusEnabled
type: booleanWhether to enable the Message Consumption Horizon feature. The default is true
.
ReachabilityEnabled
type: booleanWhether to enable the Reachability Indicator for this Service instance. The default is false
.
TypingIndicatorTimeout
type: integerHow 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.
ConsumptionReportInterval
type: integerDEPRECATED. The interval in seconds between consumption reports submission batches from client endpoints.
Notifications.NewMessage.Enabled
type: booleanWhether to send a notification when a new message is added to a channel. The default is false
.
Notifications.NewMessage.Template
type: stringThe 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.Sound
type: stringThe name of the sound to play when a new message is added to a channel and notifications.new_message.enabled
is true
.
Notifications.NewMessage.BadgeCountEnabled
type: booleanWhether the new message badge is enabled. The default is false
.
Notifications.AddedToChannel.Enabled
type: booleanWhether to send a notification when a member is added to a channel. The default is false
.
Notifications.AddedToChannel.Template
type: stringThe 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.Sound
type: stringThe name of the sound to play when a member is added to a channel and notifications.added_to_channel.enabled
is true
.
Notifications.RemovedFromChannel.Enabled
type: booleanWhether to send a notification to a user when they are removed from a channel. The default is false
.
Notifications.RemovedFromChannel.Template
type: stringThe 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.Sound
type: stringThe 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.Enabled
type: booleanWhether to send a notification when a user is invited to a channel. The default is false
.
Notifications.InvitedToChannel.Template
type: stringThe 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.Sound
type: stringThe name of the sound to play when a user is invited to a channel and notifications.invited_to_channel.enabled
is true
.
PreWebhookUrl
type: string<uri>The URL for pre-event webhooks, which are called by using the webhook_method
. See Webhook Events for more details.
PostWebhookUrl
type: string<uri>The URL for post-event webhooks, which are called by using the webhook_method
. See Webhook Events for more details.
WebhookMethod
type: enum<http-method>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.
GET
POST
WebhookFilters
type: array[string]The list of webhook events that are enabled for this Service instance. See Webhook Events for more details.
Limits.ChannelMembers
type: integerThe maximum number of Members that can be added to Channels within this Service. Can be up to 1,000.
Limits.UserChannels
type: integerThe maximum number of Channels Users can be a Member of within this Service. Can be up to 1,000.
Media.CompatibilityMessage
type: stringThe message to send when a media message has no text. Can be used as placeholder message.
PreWebhookRetryCount
type: integerThe 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.
PostWebhookRetryCount
type: integerThe 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.
DELETE https://chat.twilio.com/v2/Services/{Sid}