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:
sid
type: SID<KS>The unique string that we created to identify the Service resource.
^KS[0-9a-fA-F]{32}$
34
34
unique_name
type: stringAn 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
type: SID<AC>The SID of the Account that created the Service resource.
^AC[0-9a-fA-F]{32}$
34
34
chat_instance_sid
type: SID<IS>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.
^IS[0-9a-fA-F]{32}$
34
34
default_ttl
type: integerThe default ttl
value for Sessions created in the Service. The TTL (time to live) is measured in seconds after the Session's last create or last Interaction. The default value of 0
indicates an unlimited Session length. You can override a Session's default TTL value by setting its ttl
value.
number_selection_behavior
type: enum<string>The preference for Proxy Number selection in the Service instance. Can be: prefer-sticky
or avoid-sticky
. prefer-sticky
means that we will try and select the same Proxy Number for a given participant if they have previous Sessions, but we will not fail if that Proxy Number cannot be used. avoid-sticky
means that we will try to use different Proxy Numbers as long as that is possible within a given pool rather than try and use a previously assigned number.
avoid-sticky
prefer-sticky
geo_match_level
type: enum<string>Where a proxy number must be located relative to the participant identifier. Can be: country
, area-code
, or extended-area-code
. The default value is country
and more specific areas than country
are only available in North America.
area-code
overlay
radius
country
intercept_callback_url
type: string<uri>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
type: string<uri>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_updated
type: string<date-time>The ISO 8601 date and time in GMT when the resource was last updated.
A Twilio Phone Number or Short Code associated with a Proxy Service cannot be associated with other Proxy Services in the same account.
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.
POST https://proxy.twilio.com/v1/Services
Create a new Service.
UniqueName
type: stringRequiredAn 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.
DefaultTtl
type: integerThe default ttl
value to set for Sessions created in the Service. The TTL (time to live) is measured in seconds after the Session's last create or last Interaction. The default value of 0
indicates an unlimited Session length. You can override a Session's default TTL value by setting its ttl
value.
GeoMatchLevel
type: enum<string>Where a proxy number must be located relative to the participant identifier. Can be: country
, area-code
, or extended-area-code
. The default value is country
and more specific areas than country
are only available in North America.
area-code
overlay
radius
country
NumberSelectionBehavior
type: enum<string>The preference for Proxy Number selection in the Service instance. Can be: prefer-sticky
or avoid-sticky
and the default is prefer-sticky
. prefer-sticky
means that we will try and select the same Proxy Number for a given participant if they have previous Sessions, but we will not fail if that Proxy Number cannot be used. avoid-sticky
means that we will try to use different Proxy Numbers as long as that is possible within a given pool rather than try and use a previously assigned number.
avoid-sticky
prefer-sticky
InterceptCallbackUrl
type: string<uri>The URL we call on each interaction. If we receive a 403 status, we block the interaction; otherwise the interaction continues.
OutOfSessionCallbackUrl
type: string<uri>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.
ChatInstanceSid
type: SID<IS>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.
^IS[0-9a-fA-F]{32}$
34
34
GET https://proxy.twilio.com/v1/Services/{Sid}
Retrieve a single Service.
Sid
type: stringThe Twilio-provided string that uniquely identifies the Service resource to fetch.
GET https://proxy.twilio.com/v1/Services
Retrieve a list of all Services for a given account.
PageSize
type: integerHow many resources to return in each list page. The default is 50, and the maximum is 1000.
1
Page
type: integerThe page index. This value is simply for client state.
0
POST https://proxy.twilio.com/v1/Services/{Sid}
Update a Service's configuration.
Sid
type: SID<KS>The Twilio-provided string that uniquely identifies the Service resource to update.
^KS[0-9a-fA-F]{32}$
34
34
UniqueName
type: stringAn 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.
DefaultTtl
type: integerThe default ttl
value to set for Sessions created in the Service. The TTL (time to live) is measured in seconds after the Session's last create or last Interaction. The default value of 0
indicates an unlimited Session length. You can override a Session's default TTL value by setting its ttl
value.
GeoMatchLevel
type: enum<string>Where a proxy number must be located relative to the participant identifier. Can be: country
, area-code
, or extended-area-code
. The default value is country
and more specific areas than country
are only available in North America.
area-code
overlay
radius
country
NumberSelectionBehavior
type: enum<string>The preference for Proxy Number selection in the Service instance. Can be: prefer-sticky
or avoid-sticky
and the default is prefer-sticky
. prefer-sticky
means that we will try and select the same Proxy Number for a given participant if they have previous Sessions, but we will not fail if that Proxy Number cannot be used. avoid-sticky
means that we will try to use different Proxy Numbers as long as that is possible within a given pool rather than try and use a previously assigned number.
avoid-sticky
prefer-sticky
InterceptCallbackUrl
type: string<uri>The URL we call on each interaction. If we receive a 403 status, we block the interaction; otherwise the interaction continues.
OutOfSessionCallbackUrl
type: string<uri>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.
ChatInstanceSid
type: SID<IS>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.
^IS[0-9a-fA-F]{32}$
34
34
DELETE 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.
Sid
type: SID<KS>The Twilio-provided string that uniquely identifies the Service resource to delete.
^KS[0-9a-fA-F]{32}$
34
34