On this page

Participant

(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 Participant is a single individual communicating in a Session. There is a limit of two Participants per Session.

You can create a Proxy Participant in two ways:

By specifying the private Phone Number of the Participant (Identifier) and relying on Proxy to select an appropriate Phone Number from the Proxy Number pool. The Proxy Number returned (Proxy Identifier) is the Phone Number that the Participant should call to reach the other party.
By specifying both the Identifier and the Proxy Identifier. In this case, Proxy will attempt to use the Twilio Phone Number provided. Note: The Twilio Phone Number specified must already be added to the Proxy Number pool in order to be accepted.

Participant Properties

Property nameTypeRequiredDescriptionChild properties

sidSID<KP>

Optional

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

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

session_sidSID<KC>

Optional

The SID of the parent Session resource.

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

service_sidSID<KS>

Optional

The SID of the resource's parent Service resource.

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

account_sidSID<AC>

Optional

The SID of the Account that created the Participant resource.

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

friendly_namestring

Optional

The string that you assigned to describe the participant. This value must be 255 characters or fewer. Supports UTF-8 characters. This value should not have PII.

identifierstring

Optional

PII MTL: 30 days

The phone number or channel identifier of the Participant. This value must be 191 characters or fewer. Supports UTF-8 characters.

proxy_identifierstring

Optional

The phone number or short code (masked number) of the participant's partner. The participant will call or message the partner participant at this number.

proxy_identifier_sidSID<PN>

Optional

The SID of the Proxy Identifier assigned to the Participant.

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

date_deletedstring<date-time>

Optional

The ISO 8601 date when the Participant was removed from the session.

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 Participant resource.

linksobject<uri-map>

Optional

The URLs to resources related the participant.

Create a Participant resource

POST https://proxy.twilio.com/v1/Services/{ServiceSid}/Sessions/{SessionSid}/Participants

Path parameters

Property nameTypeRequiredPIIDescription

ServiceSidSID<KS>required

The SID of the parent Service resource.

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

SessionSidSID<KC>required

The SID of the parent Session resource.

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

Request body parameters

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

SchemaExample

Property nameTypeRequiredDescriptionChild properties

Identifierstringrequired

PII MTL: 30 days

The phone number of the Participant.

FriendlyNamestring

Optional

The string that you assigned to describe the participant. This value must be 255 characters or fewer. This value should not have PII.

ProxyIdentifierstring

Optional

The proxy phone number to use for the Participant. If not specified, Proxy will select a number from the pool.

ProxyIdentifierSidSID<PN>

Optional

The SID of the Proxy Identifier to assign to the Participant.

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

Create a Participant

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 createParticipant() {
11  const participant = await client.proxy.v1
12    .services("KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .sessions("KCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
14    .participants.create({
15      friendlyName: "Alice",
16      identifier: "+15558675310",
17    });
18
19  console.log(participant.proxyIdentifier);
20}
21
22createParticipant();

Output

1{
2  "sid": "KPaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "session_sid": "KCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
4  "service_sid": "KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
5  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6  "identifier": "+15558675310",
7  "proxy_identifier": "+14155559999",
8  "proxy_identifier_sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
9  "friendly_name": "Alice",
10  "date_deleted": "2015-07-30T20:00:00Z",
11  "date_updated": "2015-07-30T20:00:00Z",
12  "date_created": "2015-07-30T20:00:00Z",
13  "url": "https://proxy.twilio.com/v1/Services/KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Sessions/KCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/KPaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14  "links": {
15    "message_interactions": "https://proxy.twilio.com/v1/Services/KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Sessions/KCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/KPaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/MessageInteractions"
16  }
17}

Fetch a Participant resource

GET https://proxy.twilio.com/v1/Services/{ServiceSid}/Sessions/{SessionSid}/Participants/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

ServiceSidSID<KS>required

The SID of the parent Service of the resource to fetch.

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

SessionSidSID<KC>required

The SID of the parent Session of the resource to fetch.

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

SidSID<KP>required

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

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

Fetch a Participant

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 fetchParticipant() {
11  const participant = await client.proxy.v1
12    .services("KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .sessions("KCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
14    .participants("KPaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
15    .fetch();
16
17  console.log(participant.sid);
18}
19
20fetchParticipant();

Output

1{
2  "sid": "KPaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "session_sid": "KCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "service_sid": "KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6  "identifier": "+14155551212",
7  "proxy_identifier": "+14155559999",
8  "proxy_identifier_sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
9  "friendly_name": "friendly_name",
10  "date_deleted": "2015-07-30T20:00:00Z",
11  "date_updated": "2015-07-30T20:00:00Z",
12  "date_created": "2015-07-30T20:00:00Z",
13  "url": "https://proxy.twilio.com/v1/Services/KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Sessions/KCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/KPaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14  "links": {
15    "message_interactions": "https://proxy.twilio.com/v1/Services/KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Sessions/KCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/KPaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/MessageInteractions"
16  }
17}

Read multiple Participant resources

GET https://proxy.twilio.com/v1/Services/{ServiceSid}/Sessions/{SessionSid}/Participants

Path parameters

Property nameTypeRequiredPIIDescription

ServiceSidSID<KS>required

The SID of the parent Service of the resources to read.

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

SessionSidSID<KC>required

The SID of the parent Session of the resources to read.

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

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.

Update a Participant

In order to add a new Participant in a Session, you can DELETE an existing Participant and then add a new one.

(error)

Danger

Adding a participant that was removed is not possible.

Proxy will return with error 80103 if the new participant's identifier matches the deleted participant's identifier.

List multiple Participants

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 listParticipant() {
11  const participants = await client.proxy.v1
12    .services("KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .sessions("KCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
14    .participants.list({ limit: 20 });
15
16  participants.forEach((p) => console.log(p.sid));
17}
18
19listParticipant();

Output

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

Delete a Participant resource

DELETE https://proxy.twilio.com/v1/Services/{ServiceSid}/Sessions/{SessionSid}/Participants/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

ServiceSidSID<KS>required

The SID of the parent Service of the resource to delete.

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

SessionSidSID<KC>required

The SID of the parent Session of the resource to delete.

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

SidSID<KP>required

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

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

Delete a Participant

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 deleteParticipant() {
11  await client.proxy.v1
12    .services("KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .sessions("KCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
14    .participants("KPaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
15    .remove();
16}
17
18deleteParticipant();