On this page

Service

(error)

Proxy Public Beta is not available to new customers

Proxy Public Beta is currently closed for new customers. Please consider using Twilio Conversations and Programmable Voice directly if you are building your masking application.

Note that this does not have any impact on Twilio Flex customers.

(warning)

Public Beta for customers already using Proxy

Twilio's Proxy API is currently available as a Public Beta product. Some features are not yet implemented and others may be changed before the product is declared as Generally Available.

Public Beta products are not covered by a Twilio SLA.

A Service is the top-level scope of all other resources in the REST API. It owns Sessions and Proxy Numbers (like Phone Numbers 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

Property nameTypeRequiredDescriptionChild properties

sidSID<KS>

Optional

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

Pattern: ^KS[0-9a-fA-F]{32}$Min length: 34Max length: 34

unique_namestring

Optional

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_sidSID<AC>

Optional

The SID of the Account that created the Service resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

chat_instance_sidSID<IS>

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.

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34

callback_urlstring<uri>

Optional

The URL we call when the interaction status changes.

default_ttlinteger

Optional

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.

Default: 0

number_selection_behaviorenum<string>

Optional

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.

Possible values:

avoid-stickyprefer-sticky

geo_match_levelenum<string>

Optional

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_urlstring<uri>

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_urlstring<uri>

Optional

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_createdstring<date-time>

Optional

The ISO 8601 date and time in GMT when the resource was created.

date_updatedstring<date-time>

Optional

The ISO 8601 date and time in GMT when the resource was last updated.

urlstring<uri>

Optional

The absolute URL of the Service resource.

linksobject<uri-map>

Optional

The URLs of resources related to the Service.

Note on Proxy Numbers associated with Services

A Twilio Phone Number 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

POST https://proxy.twilio.com/v1/Services

Create a new Service.

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

UniqueNamestringrequired

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.

DefaultTtlinteger

Optional

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.

CallbackUrlstring<uri>

Optional

The URL we should call when the interaction status changes.

GeoMatchLevelenum<string>

Optional

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

NumberSelectionBehaviorenum<string>

Optional

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.

Possible values:

avoid-stickyprefer-sticky

InterceptCallbackUrlstring<uri>

Optional

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

OutOfSessionCallbackUrlstring<uri>

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.

ChatInstanceSidSID<IS>

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.

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34

Create a Service

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createService() {
11  const service = await client.proxy.v1.services.create({
12    uniqueName: "UniqueName",
13  });
14
15  console.log(service.sid);
16}
17
18createService();

Output

1{
2  "sid": "KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "chat_instance_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "unique_name": "UniqueName",
6  "default_ttl": 3600,
7  "callback_url": "http://www.example.com",
8  "geo_match_level": "country",
9  "number_selection_behavior": "prefer-sticky",
10  "intercept_callback_url": "http://www.example.com",
11  "out_of_session_callback_url": "http://www.example.com",
12  "date_created": "2015-07-30T20:00:00Z",
13  "date_updated": "2015-07-30T20:00:00Z",
14  "url": "https://proxy.twilio.com/v1/Services/KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15  "links": {
16    "sessions": "https://proxy.twilio.com/v1/Services/KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Sessions",
17    "phone_numbers": "https://proxy.twilio.com/v1/Services/KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/PhoneNumbers",
18    "short_codes": "https://proxy.twilio.com/v1/Services/KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ShortCodes"
19  }
20}

Fetch a Service resource

GET https://proxy.twilio.com/v1/Services/{Sid}

Retrieve a single Service.

Path parameters

Property nameTypeRequiredPIIDescription

Sidstringrequired

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

Fetch a Service

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchService() {
11  const service = await client.proxy.v1.services("Sid").fetch();
12
13  console.log(service.sid);
14}
15
16fetchService();

Output

1{
2  "sid": "Sid",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "chat_instance_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "unique_name": "My Service",
6  "default_ttl": 3600,
7  "callback_url": "http://www.example.com",
8  "geo_match_level": "country",
9  "number_selection_behavior": "prefer-sticky",
10  "intercept_callback_url": "http://www.example.com",
11  "out_of_session_callback_url": "http://www.example.com",
12  "date_created": "2015-07-30T20:00:00Z",
13  "date_updated": "2015-07-30T20:00:00Z",
14  "url": "https://proxy.twilio.com/v1/Services/KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15  "links": {
16    "sessions": "https://proxy.twilio.com/v1/Services/KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Sessions",
17    "phone_numbers": "https://proxy.twilio.com/v1/Services/KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/PhoneNumbers",
18    "short_codes": "https://proxy.twilio.com/v1/Services/KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ShortCodes"
19  }
20}

Read multiple Service resources

GET https://proxy.twilio.com/v1/Services

Retrieve a list of all Services for a given account.

Query parameters

Property nameTypeRequiredPIIDescription

PageSizeinteger

Optional

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

Minimum: 1Maximum: 1000

Pageinteger

Optional

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

Minimum: 0

PageTokenstring

Optional

The page token. This is provided by the API.

List multiple Services

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listService() {
11  const services = await client.proxy.v1.services.list({ limit: 20 });
12
13  services.forEach((s) => console.log(s.sid));
14}
15
16listService();

Output

1{
2  "services": [],
3  "meta": {
4    "first_page_url": "https://proxy.twilio.com/v1/Services?PageSize=50&Page=0",
5    "key": "services",
6    "next_page_url": null,
7    "page": 0,
8    "page_size": 50,
9    "previous_page_url": null,
10    "url": "https://proxy.twilio.com/v1/Services?PageSize=50&Page=0"
11  }
12}

Update a Service resource

POST https://proxy.twilio.com/v1/Services/{Sid}

Update a Service's configuration.

Path parameters

Property nameTypeRequiredPIIDescription

SidSID<KS>required

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

Pattern: ^KS[0-9a-fA-F]{32}$Min length: 34Max length: 34

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

UniqueNamestring

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.

DefaultTtlinteger

Optional

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.

CallbackUrlstring<uri>

Optional

The URL we should call when the interaction status changes.

GeoMatchLevelenum<string>

Optional

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

NumberSelectionBehaviorenum<string>

Optional

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.

Possible values:

avoid-stickyprefer-sticky

InterceptCallbackUrlstring<uri>

Optional

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

OutOfSessionCallbackUrlstring<uri>

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.

ChatInstanceSidSID<IS>

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.

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34

Update a Service

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function updateService() {
11  const service = await client.proxy.v1
12    .services("KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .update({ uniqueName: "UniqueName" });
14
15  console.log(service.sid);
16}
17
18updateService();

Output

1{
2  "sid": "KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "chat_instance_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "unique_name": "UniqueName",
6  "default_ttl": 3600,
7  "callback_url": "http://www.example.com",
8  "geo_match_level": "country",
9  "number_selection_behavior": "prefer-sticky",
10  "intercept_callback_url": "http://www.example.com",
11  "out_of_session_callback_url": "http://www.example.com",
12  "date_created": "2015-07-30T20:00:00Z",
13  "date_updated": "2015-07-30T20:00:00Z",
14  "url": "https://proxy.twilio.com/v1/Services/KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15  "links": {
16    "sessions": "https://proxy.twilio.com/v1/Services/KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Sessions",
17    "phone_numbers": "https://proxy.twilio.com/v1/Services/KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/PhoneNumbers",
18    "short_codes": "https://proxy.twilio.com/v1/Services/KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ShortCodes"
19  }
20}

Delete a Service resource

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

Path parameters

Property nameTypeRequiredPIIDescription

SidSID<KS>required

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

Pattern: ^KS[0-9a-fA-F]{32}$Min length: 34Max length: 34

Delete a Service

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function deleteService() {
11  await client.proxy.v1.services("KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa").remove();
12}
13
14deleteService();