Service
A Service is the top-level scope of all other resources in the REST API. It owns Sessions and Proxy Numbers (e.g. Phone Numbers and Short Codes) for a Proxy application. Services allow you to:
- Create multiple environments (e.g. dev, stage, and prod) under the same Twilio account with segregated data
- Scope access to resources through the REST API
- Configure behavior of the Service per instance
Service properties
| Resource Properties in REST API format | |
|---|---|
sid
|
The unique string that we created to identify the Service resource. |
unique_name
|
An application-defined string that uniquely identifies the resource. This value must be 191 characters or fewer in length and be unique. Supports UTF-8 characters. This value should not have PII. |
account_sid
|
The SID of the Account that created the Service resource. |
chat_instance_sid
|
The SID of the Chat Service Instance managed by Proxy Service. The Chat Service enables Proxy to forward SMS and channel messages to this chat instance. This is a one-to-one relationship. |
callback_url
|
The URL we call when the interaction status changes. |
default_ttl
|
The default |
number_selection_behavior
|
The preference for Proxy Number selection in the Service instance. Can be: |
geo_match_level
|
Where a proxy number must be located relative to the participant identifier. Can be: |
intercept_callback_url
|
The URL we call on each interaction. If we receive a 403 status, we block the interaction; otherwise the interaction continues. |
out_of_session_callback_url
|
The URL we call when an inbound call or SMS action occurs on a closed or non-existent Session. If your server (or a Twilio function) responds with valid TwiML, we will process it. This means it is possible, for example, to play a message for a call, send an automated text message response, or redirect a call to another Phone Number. See Out-of-Session Callback Response Guide for more information. |
date_created
|
The ISO 8601 date and time in GMT when the resource was created. |
date_updated
|
The ISO 8601 date and time in GMT when the resource was last updated. |
url
|
The absolute URL of the Service resource. |
links
|
The URLs of resources related to the Service. |
Note on Proxy Numbers associated with Services
A Twilio Phone Number or Short Code associated with a Proxy Service cannot be associated with other Proxy Services in the same account.
Learning about Proxy Number management
A Proxy Service contains a lot of detailed configuration options regarding Proxy Number selection logic. If you'd like to learn more about how Proxy handles Proxy Numbers, check out the Proxy Number Management explanation page.
Create a Service resource
https://proxy.twilio.com/v1/Services
Create a new Service.
Parameters
| Parameters in REST API format | |
|---|---|
unique_name
Required
|
An application-defined string that uniquely identifies the resource. This value must be 191 characters or fewer in length and be unique. This value should not have PII. |
default_ttl
Optional
|
The default |
callback_url
Optional
|
The URL we should call when the interaction status changes. |
geo_match_level
Optional
|
Where a proxy number must be located relative to the participant identifier. Can be: |
number_selection_behavior
Optional
|
The preference for Proxy Number selection in the Service instance. Can be: |
intercept_callback_url
Optional
|
The URL we call on each interaction. If we receive a 403 status, we block the interaction; otherwise the interaction continues. |
out_of_session_callback_url
Optional
|
The URL we should call when an inbound call or SMS action occurs on a closed or non-existent Session. If your server (or a Twilio function) responds with valid TwiML, we will process it. This means it is possible, for example, to play a message for a call, send an automated text message response, or redirect a call to another Phone Number. See Out-of-Session Callback Response Guide for more information. |
chat_instance_sid
Optional
|
The SID of the Chat Service Instance managed by Proxy Service. The Chat Service enables Proxy to forward SMS and channel messages to this chat instance. This is a one-to-one relationship. |
Example 1
Fetch a Service resource
https://proxy.twilio.com/v1/Services/{Sid}
Retrieve a single Service.
Parameters
| Parameters in REST API format | |
|---|---|
sid
Path
|
The Twilio-provided string that uniquely identifies the Service resource to fetch. |
Example 1
Read multiple Service resources
https://proxy.twilio.com/v1/Services
Retrieve a list of all Services for a given account.
Example 1
Update a Service resource
https://proxy.twilio.com/v1/Services/{Sid}
Update a Service's configuration.
Parameters
| Parameters in REST API format | |
|---|---|
sid
Path
|
The Twilio-provided string that uniquely identifies the Service resource to update. |
unique_name
Optional
|
An application-defined string that uniquely identifies the resource. This value must be 191 characters or fewer in length and be unique. This value should not have PII. |
default_ttl
Optional
|
The default |
callback_url
Optional
|
The URL we should call when the interaction status changes. |
geo_match_level
Optional
|
Where a proxy number must be located relative to the participant identifier. Can be: |
number_selection_behavior
Optional
|
The preference for Proxy Number selection in the Service instance. Can be: |
intercept_callback_url
Optional
|
The URL we call on each interaction. If we receive a 403 status, we block the interaction; otherwise the interaction continues. |
out_of_session_callback_url
Optional
|
The URL we should call when an inbound call or SMS action occurs on a closed or non-existent Session. If your server (or a Twilio function) responds with valid TwiML, we will process it. This means it is possible, for example, to play a message for a call, send an automated text message response, or redirect a call to another Phone Number. See Out-of-Session Callback Response Guide for more information. |
chat_instance_sid
Optional
|
The SID of the Chat Service Instance managed by Proxy Service. The Chat Service enables Proxy to forward SMS and channel messages to this chat instance. This is a one-to-one relationship. |
Example 1
Delete a Service resource
https://proxy.twilio.com/v1/Services/{Sid}
Permanently delete a Service and all children (Sessions, Participants, Interactions). In addition, all associated Proxy Numbers (e.g. Phone Numbers and Short Codes) will become available for assignment to another Service.
Any Message or Call records created during interactions for Sessions in this Service will NOT be deleted automatically. If you want to delete all related Message/Call resources, you must issue direct DELETE requests for the inbound and outbound resources of all child Interactions directly. Once you have deleted a Service, those resource Sids will not be discoverable via Proxy.
Parameters
| Parameters in REST API format | |
|---|---|
sid
Path
|
The Twilio-provided string that uniquely identifies 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.
