Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

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 the behavior of the Service per instance

Service Properties

service-properties page anchor
Resource properties
sidtype: SID<KS>Not PII

The unique string that we created to identify the Service resource.


unique_nametype: stringNot PII

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.


chat_instance_sidtype: SID<IS>Not PII

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_urltype: string<URI>Not PII

The URL we call when the interaction status changes.


default_ttltype: integerNot PII

The 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_behaviortype: enum<STRING>Not PII

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(link takes you to an external page), 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.

Possible values:
avoid-stickyprefer-sticky

geo_match_leveltype: enum<STRING>Not PII

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.

Possible values:
area-codeoverlayradiuscountry

intercept_callback_urltype: string<URI>Not PII

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_urltype: string<URI>Not PII

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(link takes you to an external page)) responds with valid TwiML(link takes you to an external page), 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(link takes you to an external page) for more information.


date_createdtype: string<DATE TIME>Not PII

The ISO 8601(link takes you to an external page) date and time in GMT when the resource was created.


date_updatedtype: string<DATE TIME>Not PII

The ISO 8601(link takes you to an external page) date and time in GMT when the resource was last updated.


urltype: string<URI>Not PII

The absolute URL of the Service resource.


linkstype: object<URI MAP>Not PII

The URLs of resources related to the Service.


Note on Proxy Numbers associated with Services

note-on-proxy-numbers-associated-with-services page anchor

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

learning-about-proxy-number-management page anchor

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

create-a-service-resource page anchor
POST https://proxy.twilio.com/v1/Services

Create a new Service.

Parameters

create-parameters page anchor
Request body parameters
UniqueNametype: stringNot PII
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.


DefaultTtltype: integerNot PII

The 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.


CallbackUrltype: string<URI>Not PII

The URL we should call when the interaction status changes.


GeoMatchLeveltype: enum<STRING>Not PII

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.

Possible values:
area-codeoverlayradiuscountry

NumberSelectionBehaviortype: enum<STRING>Not PII

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(link takes you to an external page), 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.

Possible values:
avoid-stickyprefer-sticky

InterceptCallbackUrltype: string<URI>Not PII

The URL we call on each interaction. If we receive a 403 status, we block the interaction; otherwise the interaction continues.


OutOfSessionCallbackUrltype: string<URI>Not PII

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(link takes you to an external page)) responds with valid TwiML(link takes you to an external page), 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(link takes you to an external page) for more information.


ChatInstanceSidtype: SID<IS>Not PII

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.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.proxy.v1.services.create({uniqueName: 'unique_name'})
_10
.then(service => console.log(service.sid));

Output

_20
{
_20
"sid": "KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"chat_instance_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"unique_name": "My Service",
_20
"default_ttl": 3600,
_20
"callback_url": "http://www.example.com",
_20
"geo_match_level": "country",
_20
"number_selection_behavior": "prefer-sticky",
_20
"intercept_callback_url": "http://www.example.com",
_20
"out_of_session_callback_url": "http://www.example.com",
_20
"date_created": "2015-07-30T20:00:00Z",
_20
"date_updated": "2015-07-30T20:00:00Z",
_20
"url": "https://proxy.twilio.com/v1/Services/KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"links": {
_20
"sessions": "https://proxy.twilio.com/v1/Services/KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Sessions",
_20
"phone_numbers": "https://proxy.twilio.com/v1/Services/KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/PhoneNumbers",
_20
"short_codes": "https://proxy.twilio.com/v1/Services/KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ShortCodes"
_20
}
_20
}


Fetch a Service resource

fetch-a-service-resource page anchor
GET https://proxy.twilio.com/v1/Services/{Sid}

Retrieve a single Service.

URI parameters
Sidtype: stringNot PII
Path Parameter

The Twilio-provided string that uniquely identifies the Service resource to fetch.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.proxy.v1.services('KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.fetch()
_10
.then(service => console.log(service.uniqueName));

Output

_20
{
_20
"sid": "KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"chat_instance_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"unique_name": "My Service",
_20
"default_ttl": 3600,
_20
"callback_url": "http://www.example.com",
_20
"geo_match_level": "country",
_20
"number_selection_behavior": "prefer-sticky",
_20
"intercept_callback_url": "http://www.example.com",
_20
"out_of_session_callback_url": "http://www.example.com",
_20
"date_created": "2015-07-30T20:00:00Z",
_20
"date_updated": "2015-07-30T20:00:00Z",
_20
"url": "https://proxy.twilio.com/v1/Services/KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"links": {
_20
"sessions": "https://proxy.twilio.com/v1/Services/KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Sessions",
_20
"phone_numbers": "https://proxy.twilio.com/v1/Services/KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/PhoneNumbers",
_20
"short_codes": "https://proxy.twilio.com/v1/Services/KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ShortCodes"
_20
}
_20
}


Read multiple Service resources

read-multiple-service-resources page anchor
GET https://proxy.twilio.com/v1/Services

Retrieve a list of all Services for a given account.

URI parameters
PageSizetype: integerNot PII
Query Parameter

How many resources to return in each list page. The default is 50, and the maximum is 1000.


Pagetype: integerNot PII
Query Parameter

The page index. This value is simply for client state.


PageTokentype: stringNot PII
Query Parameter

The page token. This is provided by the API.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.proxy.v1.services.list({limit: 20})
_10
.then(services => services.forEach(s => console.log(s.sid)));

Output

_12
{
_12
"services": [],
_12
"meta": {
_12
"first_page_url": "https://proxy.twilio.com/v1/Services?PageSize=50&Page=0",
_12
"key": "services",
_12
"next_page_url": "https://proxy.twilio.com/v1/Services?PageSize=50&Page=1",
_12
"page": 0,
_12
"page_size": 50,
_12
"previous_page_url": "https://proxy.twilio.com/v1/Services?PageSize=50&Page=0",
_12
"url": "https://proxy.twilio.com/v1/Services?PageSize=50&Page=0"
_12
}
_12
}


Update a Service resource

update-a-service-resource page anchor
POST https://proxy.twilio.com/v1/Services/{Sid}

Update a Service's configuration.

URI parameters
Sidtype: SID<KS>Not PII
Path Parameter

The Twilio-provided string that uniquely identifies the Service resource to update.


Request body parameters
UniqueNametype: stringNot PII

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.


DefaultTtltype: integerNot PII

The 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.


CallbackUrltype: string<URI>Not PII

The URL we should call when the interaction status changes.


GeoMatchLeveltype: enum<STRING>Not PII

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.

Possible values:
area-codeoverlayradiuscountry

NumberSelectionBehaviortype: enum<STRING>Not PII

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(link takes you to an external page), 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.

Possible values:
avoid-stickyprefer-sticky

InterceptCallbackUrltype: string<URI>Not PII

The URL we call on each interaction. If we receive a 403 status, we block the interaction; otherwise the interaction continues.


OutOfSessionCallbackUrltype: string<URI>Not PII

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(link takes you to an external page)) responds with valid TwiML(link takes you to an external page), 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(link takes you to an external page) for more information.


ChatInstanceSidtype: SID<IS>Not PII

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.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.proxy.v1.services('KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.update({uniqueName: 'unique_name'})
_10
.then(service => console.log(service.uniqueName));

Output

_20
{
_20
"sid": "KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"chat_instance_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"unique_name": "My Service",
_20
"default_ttl": 3600,
_20
"callback_url": "http://www.example.com",
_20
"geo_match_level": "country",
_20
"number_selection_behavior": "prefer-sticky",
_20
"intercept_callback_url": "http://www.example.com",
_20
"out_of_session_callback_url": "http://www.example.com",
_20
"date_created": "2015-07-30T20:00:00Z",
_20
"date_updated": "2015-07-30T20:00:00Z",
_20
"url": "https://proxy.twilio.com/v1/Services/KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"links": {
_20
"sessions": "https://proxy.twilio.com/v1/Services/KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Sessions",
_20
"phone_numbers": "https://proxy.twilio.com/v1/Services/KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/PhoneNumbers",
_20
"short_codes": "https://proxy.twilio.com/v1/Services/KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ShortCodes"
_20
}
_20
}


Delete a Service resource

delete-a-service-resource page anchor
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.

(error)

Danger

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.

URI parameters
Sidtype: SID<KS>Not PII
Path Parameter

The Twilio-provided string that uniquely identifies the Service resource to delete.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.proxy.v1.services('KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX').remove();


Rate this page: