Service Resource

Public Beta

The Service Resource is currently available as a Public Beta product. This means that some features for configuring your Messaging Service via the REST API are not yet implemented, and others may be changed before the product is declared Generally Available. Messaging Service Configuration through the Twilio Console is Generally Available.

Public Beta products are not covered by a Twilio SLA.

The resources for sending Messages with a Messaging Service are Generally Available.

When sending a message with a Messaging Service, you can improve message performance by enabling the included features.

Developers can associate phone numbers, short codes, and alpha sender IDs to an instance of a Messaging Service. The Service handles all inbound and outbound behaviors for the phone numbers and shortcodes.

Twilio Console

You can manage your Messaging Services through the Twilio Console when logged in.

Messaging Services Resource

The Services resource of Messaging represents a set of configurable behavior for sending and receiving Messages.

Subresources

The Services resource also has phone numbers, short codes, and alpha sender IDs subresources for managing the phone numbers, short codes, and alpha sender IDs associated with the Service.

Resource URI

All URLs in this documentation use the following base URL:

https://messaging.twilio.com/v1

Service properties

Resource Properties in REST API format
`sid`	sid<MG> Not PII The unique string that we created to identify the Service resource.
`account_sid`	sid<AC> Not PII The SID of the Account that created the Service resource.
`friendly_name`	string Not PII The string that you assigned to describe the resource.
`date_created`	date_time<iso8601> Not PII The date and time in GMT when the resource was created specified in ISO 8601 format.
`date_updated`	date_time<iso8601> Not PII The date and time in GMT when the resource was last updated specified in ISO 8601 format.
`inbound_request_url`	url Not PII The URL we call using `inbound_method` when a message is received by any phone number or short code in the Service. When this property is `null`, receiving inbound messages is disabled. All messages sent to the Twilio phone number or short code will not be logged and received on the Account. If the `use_inbound_webhook_on_number` field is enabled then the webhook url defined on the phone number will override the `inbound_request_url` defined for the Messaging Service.
`inbound_method`	http_method Not PII The HTTP method we use to call `inbound_request_url`. Can be `GET` or `POST`.
`fallback_url`	url Not PII The URL that we call using `fallback_method` if an error occurs while retrieving or executing the TwiML from the Inbound Request URL. If the `use_inbound_webhook_on_number` field is enabled then the webhook url defined on the phone number will override the `fallback_url` defined for the Messaging Service.
`fallback_method`	http_method Not PII The HTTP method we use to call `fallback_url`. Can be: `GET` or `POST`.
`status_callback`	url Not PII The URL we call to pass status updates about message delivery.
`sticky_sender`	boolean Not PII Whether to enable Sticky Sender on the Service instance.
`mms_converter`	boolean Not PII Whether to enable the MMS Converter for messages sent through the Service instance.
`smart_encoding`	boolean Not PII Whether to enable Smart Encoding for messages sent through the Service instance.
`scan_message_content`	enum:scan_message_content Not PII Reserved.
`area_code_geomatch`	boolean Not PII Whether to enable Area Code Geomatch on the Service Instance.
`synchronous_validation`	boolean Not PII Reserved.
`validity_period`	integer Not PII How long, in seconds, messages sent from the Service are valid. Can be an integer from `1` to `14,400`.
`url`	url Not PII The absolute URL of the Service resource.
`links`	uri_map Not PII The absolute URLs of related resources.
`usecase`	string Not PII A string that describes the scenario in which the Messaging Service will be used. Possible values are `notifications`, `marketing`, `verification`, `discussion`, `poll`, `undeclared`.
`us_app_to_person_registered`	boolean Not PII Whether US A2P campaign is registered for this Service.
`use_inbound_webhook_on_number`	boolean Not PII A boolean value that indicates either the webhook url configured on the phone number will be used or `inbound_request_url`/`fallback_url` url will be called when a message is received from the phone number. If this field is enabled then the webhook url defined on the phone number will override the `inbound_request_url`/`fallback_url` defined for the Messaging Service.

Create a Service resource

post

https://messaging.twilio.com/v1/Services

Parameters

Parameters in REST API format
`friendly_name` Required	post string Not PII A descriptive string that you create to describe the resource. It can be up to 64 characters long.
`inbound_request_url` Optional	post url Not PII The URL we call using `inbound_method` when a message is received by any phone number or short code in the Service. When this property is `null`, receiving inbound messages is disabled. All messages sent to the Twilio phone number or short code will not be logged and received on the Account. If the `use_inbound_webhook_on_number` field is enabled then the webhook url defined on the phone number will override the `inbound_request_url` defined for the Messaging Service.
`inbound_method` Optional	post http_method Not PII The HTTP method we should use to call `inbound_request_url`. Can be `GET` or `POST` and the default is `POST`.
`fallback_url` Optional	post url Not PII The URL that we call using `fallback_method` if an error occurs while retrieving or executing the TwiML from the Inbound Request URL. If the `use_inbound_webhook_on_number` field is enabled then the webhook url defined on the phone number will override the `fallback_url` defined for the Messaging Service.
`fallback_method` Optional	post http_method Not PII The HTTP method we should use to call `fallback_url`. Can be: `GET` or `POST`.
`status_callback` Optional	post url Not PII The URL we should call to pass status updates about message delivery.
`sticky_sender` Optional	post boolean Not PII Whether to enable Sticky Sender on the Service instance.
`mms_converter` Optional	post boolean Not PII Whether to enable the MMS Converter for messages sent through the Service instance.
`smart_encoding` Optional	post boolean Not PII Whether to enable Smart Encoding for messages sent through the Service instance.
`scan_message_content` Optional	post enum:scan_message_content Not PII Reserved.
`area_code_geomatch` Optional	post boolean Not PII Whether to enable Area Code Geomatch on the Service Instance.
`validity_period` Optional	post integer Not PII How long, in seconds, messages sent from the Service are valid. Can be an integer from `1` to `14,400`.
`synchronous_validation` Optional	post boolean Not PII Reserved.
`usecase` Optional	post string Not PII A string that describes the scenario in which the Messaging Service will be used. Possible values are `notifications`, `marketing`, `verification`, `discussion`, `poll`, `undeclared`.
`use_inbound_webhook_on_number` Optional	post boolean Not PII A boolean value that indicates either the webhook url configured on the phone number will be used or `inbound_request_url`/`fallback_url` url will be called when a message is received from the phone number. If this field is enabled then the webhook url defined on the phone number will override the `inbound_request_url`/`fallback_url` defined for the Messaging Service.

Example 1

Loading Code Sample...

Example JSON response

Create Service

Fetch a Service resource

get

https://messaging.twilio.com/v1/Services/{Sid}

Parameters

Parameters in REST API format
`sid` Path	get sid<MG> Not PII The SID of the Service resource to fetch.

Parameters in REST API format

sid

Path

get sid<MG> Not PII

The SID of the Service resource to fetch.

Example 1

Loading Code Sample...

Example JSON response

Fetch Service

Read multiple Service resources

get

https://messaging.twilio.com/v1/Services

Example 1

Loading Code Sample...

Example JSON response

Read Service

Update a Service resource

post

https://messaging.twilio.com/v1/Services/{Sid}

You may specify one or more of the optional parameters above to update the Service's respective properties. Parameters not specified in your request are not updated.

Parameters

Parameters in REST API format
`sid` Path	post sid<MG> Not PII The SID of the Service resource to update.
`friendly_name` Optional	post string Not PII A descriptive string that you create to describe the resource. It can be up to 64 characters long.
`inbound_request_url` Optional	post url Not PII The URL we call using `inbound_method` when a message is received by any phone number or short code in the Service. When this property is `null`, receiving inbound messages is disabled. All messages sent to the Twilio phone number or short code will not be logged and received on the Account. If the `use_inbound_webhook_on_number` field is enabled then the webhook url defined on the phone number will override the `inbound_request_url` defined for the Messaging Service.
`inbound_method` Optional	post http_method Not PII The HTTP method we should use to call `inbound_request_url`. Can be `GET` or `POST` and the default is `POST`.
`fallback_url` Optional	post url Not PII The URL that we call using `fallback_method` if an error occurs while retrieving or executing the TwiML from the Inbound Request URL. If the `use_inbound_webhook_on_number` field is enabled then the webhook url defined on the phone number will override the `fallback_url` defined for the Messaging Service.
`fallback_method` Optional	post http_method Not PII The HTTP method we should use to call `fallback_url`. Can be: `GET` or `POST`.
`status_callback` Optional	post url Not PII The URL we should call to pass status updates about message delivery.
`sticky_sender` Optional	post boolean Not PII Whether to enable Sticky Sender on the Service instance.
`mms_converter` Optional	post boolean Not PII Whether to enable the MMS Converter for messages sent through the Service instance.
`smart_encoding` Optional	post boolean Not PII Whether to enable Smart Encoding for messages sent through the Service instance.
`scan_message_content` Optional	post enum:scan_message_content Not PII Reserved.
`area_code_geomatch` Optional	post boolean Not PII Whether to enable Area Code Geomatch on the Service Instance.
`validity_period` Optional	post integer Not PII How long, in seconds, messages sent from the Service are valid. Can be an integer from `1` to `14,400`.
`synchronous_validation` Optional	post boolean Not PII Reserved.
`usecase` Optional	post string Not PII A string that describes the scenario in which the Messaging Service will be used. Possible values are `notifications`, `marketing`, `verification`, `discussion`, `poll`, `undeclared`.
`use_inbound_webhook_on_number` Optional	post boolean Not PII A boolean value that indicates either the webhook url configured on the phone number will be used or `inbound_request_url`/`fallback_url` url will be called when a message is received from the phone number. If this field is enabled then the webhook url defined on the phone number will override the `inbound_request_url`/`fallback_url` defined for the Messaging Service.

Example 1

Loading Code Sample...

Example JSON response

Update Service

Delete a Service resource

delete

https://messaging.twilio.com/v1/Services/{Sid}

When a Service is deleted, all phone numbers and short codes in the Service are returned to your Account.

NOTE: One specific use for Messaging Services is to associate them with A2P Campaigns, which is the new protocol for sending automated SMS messages via 10DLC Senders within the United States. If you are using a Messaging Service for this use case, it is important to understand that once your Campaign has been approved by the A2P ecosystem, you should NOT subsequently delete the associated Messaging Service as this will also delete the Campaign itself, which will immediately de-register any 10DLC senders in that MS and thus halt their ability to message within the U.S., until a new Campaign can be registered using those same 10DLC numbers.

This warning applies ONLY to the US A2P 10DLC use case. It does not apply to Messaging Services used for messaging outsider of the U.S., or to Messaging Services using Toll Free numbers, short codes or WhatsApp senders. To learn more about A2P US 10DLC registration, please see this guide.

Twilio is working on making A2P registration a more straightforward user experience moving forward.

Parameters

Parameters in REST API format
`sid` Path	delete sid<MG> Not PII The SID of the Service resource to delete.

Parameters in REST API format

sid

Path

delete sid<MG> Not PII

The SID of the Service resource to delete.

Example 1

Loading Code Sample...

Example JSON response

Delete Service

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.

Parameters

Example 1

Create Service

Parameters

Example 1

Fetch Service

Example 1

Read Service

Parameters

Example 1

Update Service

Parameters

Example 1

Delete Service

Need some help?

Thank you for your feedback!

Thanks for your feedback!