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.
The Services resource of Messaging represents a set of configurable behavior for sending and receiving Messages.
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.
All URLs in this documentation use the following base URL:
_10https://messaging.twilio.com/v1
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.
inbound_request_url
type: string<uri>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
type: enum<http-method>The HTTP method we use to call inbound_request_url
. Can be GET
or POST
.
GET
POST
fallback_url
type: string<uri>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
type: enum<http-method>The HTTP method we use to call fallback_url
. Can be: GET
or POST
.
GET
POST
mms_converter
type: booleanWhether to enable the MMS Converter for messages sent through the Service instance.
smart_encoding
type: booleanWhether to enable Smart Encoding for messages sent through the Service instance.
fallback_to_long_code
type: boolean[OBSOLETE] Former feature used to fallback to long code sender after certain short code message failures.
validity_period
type: integerHow long, in seconds, messages sent from the Service are valid. Can be an integer from 1
to 14,400
.
usecase
type: stringA 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
type: booleanWhether US A2P campaign is registered for this Service.
use_inbound_webhook_on_number
type: booleanA 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.
sending_windows
type: objectA list of Sending Windows, which indicate defined time ranges in which a message can be sent, in the UTC time zone. Each window is defined by two strings, labeled "start_time" and "end_time".
POST https://messaging.twilio.com/v1/Services
FriendlyName
type: stringRequiredA descriptive string that you create to describe the resource. It can be up to 64 characters long.
InboundRequestUrl
type: string<uri>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.
InboundMethod
type: enum<http-method>The HTTP method we should use to call inbound_request_url
. Can be GET
or POST
and the default is POST
.
GET
POST
FallbackUrl
type: string<uri>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.
FallbackMethod
type: enum<http-method>The HTTP method we should use to call fallback_url
. Can be: GET
or POST
.
GET
POST
StatusCallback
type: string<uri>The URL we should call to pass status updates about message delivery.
MmsConverter
type: booleanWhether to enable the MMS Converter for messages sent through the Service instance.
SmartEncoding
type: booleanWhether to enable Smart Encoding for messages sent through the Service instance.
FallbackToLongCode
type: boolean[OBSOLETE] Former feature used to fallback to long code sender after certain short code message failures.
ValidityPeriod
type: integerHow long, in seconds, messages sent from the Service are valid. Can be an integer from 1
to 14,400
.
Usecase
type: stringA string that describes the scenario in which the Messaging Service will be used. Possible values are notifications
, marketing
, verification
, discussion
, poll
, undeclared
.
UseInboundWebhookOnNumber
type: booleanA 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.
GET https://messaging.twilio.com/v1/Services/{Sid}
GET https://messaging.twilio.com/v1/Services
PageSize
type: integerHow many resources to return in each list page. The default is 50, and the maximum is 1000.
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.
FriendlyName
type: stringA descriptive string that you create to describe the resource. It can be up to 64 characters long.
InboundRequestUrl
type: string<uri>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.
InboundMethod
type: enum<http-method>The HTTP method we should use to call inbound_request_url
. Can be GET
or POST
and the default is POST
.
GET
POST
FallbackUrl
type: string<uri>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.
FallbackMethod
type: enum<http-method>The HTTP method we should use to call fallback_url
. Can be: GET
or POST
.
GET
POST
StatusCallback
type: string<uri>The URL we should call to pass status updates about message delivery.
MmsConverter
type: booleanWhether to enable the MMS Converter for messages sent through the Service instance.
SmartEncoding
type: booleanWhether to enable Smart Encoding for messages sent through the Service instance.
FallbackToLongCode
type: boolean[OBSOLETE] Former feature used to fallback to long code sender after certain short code message failures.
ValidityPeriod
type: integerHow long, in seconds, messages sent from the Service are valid. Can be an integer from 1
to 14,400
.
Usecase
type: stringA string that describes the scenario in which the Messaging Service will be used. Possible values are notifications
, marketing
, verification
, discussion
, poll
, undeclared
.
UseInboundWebhookOnNumber
type: booleanA 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.
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.
If you are using a Messaging Service for A2P 10DLC, you should not delete the Messaging Service. Doing so deletes the A2P 10DLC Campaign, which immediately halts all US A2P 10DLC messaging. A new Campaign and Messaging Service must be created and re-registered. This process can take several days.