Conversations API (v2) - Participant endpoints

(information)

Legal information

Conversation Orchestrator, including the APIs, may use artificial intelligence or machine learning technologies and is subject to the terms of the Predictive and Generative AI/ML Features Addendum. For details on AI usage and data, see the AI Nutrition Facts for Real-Time Transcription and Conversation Relay.

Conversation Orchestrator is not a HIPAA Eligible Service or PCI compliant and should not be enabled in workflows that are subject to HIPAA or PCI.

Conversations products are only available in the new Twilio Console. If your account hasn't been migrated, you'll be redirected to the legacy Console where these products won't appear.

Overview

A participant represents an actor involved in a conversation. Conversation Orchestrator assigns each participant a type that identifies their role, such as customer, human agent, or AI agent.

Endpoints

/v2/Conversations/{ConversationSid}/Participants

Create Participant

/v2/Conversations/{ConversationSid}/Participants

List Participants

/v2/Conversations/{ConversationSid}/Participants/{Sid}

Fetch Participant

/v2/Conversations/{ConversationSid}/Participants/{Sid}

Update a Participant

Create Participant

POST/v2/Conversations/{ConversationSid}/Participants

Base url: https://conversations.twilio.com (base url)

Create a Participant.

Request

Security: Basic Auth

Path parameters

Property nameTypeRequiredPIIDescription

conversationSidstring

required

Request body

Encoding type:application/json

Schema

Property nameTypeRequiredPIIDescriptionChild properties

namestring

Optional

Example: Dana

typeenum<string>

Optional

Possible values:

HUMAN_AGENTCUSTOMERAI_AGENTAGENTUNKNOWN

profileIdstring

Optional

addressesarray[object]

required

Show addresses properties

Responses

201400404409429500503

Created

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

idstring

Optional

Participant ID.

Example: conv_participant_01k1etx3jbfx88476ccja0889c

conversationIdstring

Optional

Conversation ID.

Example: conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2

accountIdstring

Optional

Account ID.

Example: ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

namestring

Optional

Participant display name.

Example: Dana S.

typeenum<string>

Optional

Type of Participant in the Conversation.

Example: CUSTOMERPossible values:

HUMAN_AGENTCUSTOMERAI_AGENTAGENTUNKNOWN

profileIdstring

Optional

Profile ID. Note: This field is only resolved for CUSTOMER participant types, not for HUMAN_AGENT or AI_AGENT participants.

Example: mem_profile_00000000000000000000000000

addressesarray[object]

Optional

Communication addresses for this Participant. Address format varies by channel:

SMS/VOICE: E.164 phone number (such as "+18005550100")
EMAIL: Email address (such as "user@example.com")
WHATSAPP: Phone number with whatsapp prefix (such as "whatsapp:+18005550100")
RCS: Sender ID or phone number with rcs prefix (such as "rcs:brand_acme_agent" or "rcs:+18005550100")

Show addresses properties

createdAtstring<date-time>

Optional

Timestamp when this Participant was created.

Example: 2023-07-01T12:00:00Z

updatedAtstring<date-time>

Optional

Timestamp when this Participant was last updated.

Example: 2023-07-01T12:00:00Z

Create 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 createParticipantInConversation() {
11  const participant = await client.conversations.v2
12    .participants("ConversationSid")
13    .create({
14      addresses: [
15        {
16          channel: "VOICE",
17          address: "address",
18          channelId: "channelId",
19        },
20      ],
21    });
22
23  console.log(participant.id);
24}
25
26createParticipantInConversation();

Response

1{
2  "accountId": "ZGkrHSypTsudrGkmdpJJ",
3  "addresses": [
4    {
5      "channel": "VOICE",
6      "address": "address",
7      "channelId": "channelId"
8    }
9  ],
10  "conversationId": "conversationId",
11  "createdAt": "2009-07-06T20:30:00Z",
12  "id": "id",
13  "name": "Miss Christine Morgan",
14  "profileId": "profileId",
15  "type": "CUSTOMER",
16  "updatedAt": "2009-07-06T20:30:00Z"
17}

List Participants

GET/v2/Conversations/{ConversationSid}/Participants

Base url: https://conversations.twilio.com (base url)

Retrieve a list of Participants in a Conversation.

Request

Security: Basic Auth

Path parameters

Property nameTypeRequiredPIIDescription

conversationSidstring

required

Query string

Property nameTypeRequiredPIIDescription

pageSizeinteger

Optional

Maximum number of items to return

Default: 50Example: 50Minimum: 1Maximum: 1000

pageTokenstring

Optional

Page token for pagination

Responses

200400404429500503

OK

Schema

Property nameTypeRequiredPIIDescriptionChild properties

participantsarray[object]

Optional

Show participants properties

Property nameTypeRequiredPIIDescriptionChild properties

idstring

Optional

Participant ID.

Example: conv_participant_01k1etx3jbfx88476ccja0889c

conversationIdstring

Optional

Conversation ID.

Example: conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2

accountIdstring

Optional

Account ID.

Example: ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

namestring

Optional

Participant display name.

Example: Dana S.

typeenum<string>

Optional

Type of Participant in the Conversation.

Example: CUSTOMERPossible values:

HUMAN_AGENTCUSTOMERAI_AGENTAGENTUNKNOWN

profileIdstring

Optional

Profile ID. Note: This field is only resolved for CUSTOMER participant types, not for HUMAN_AGENT or AI_AGENT participants.

Example: mem_profile_00000000000000000000000000

addressesarray[object]

Optional

Communication addresses for this Participant. Address format varies by channel:

SMS/VOICE: E.164 phone number (such as "+18005550100")
EMAIL: Email address (such as "user@example.com")
WHATSAPP: Phone number with whatsapp prefix (such as "whatsapp:+18005550100")
RCS: Sender ID or phone number with rcs prefix (such as "rcs:brand_acme_agent" or "rcs:+18005550100")

Show addresses properties

createdAtstring<date-time>

Optional

Timestamp when this Participant was created.

Example: 2023-07-01T12:00:00Z

updatedAtstring<date-time>

Optional

Timestamp when this Participant was last updated.

Example: 2023-07-01T12:00:00Z

metaobject

Optional

Show meta properties

List 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 listParticipantByConversation() {
11  const participants = await client.conversations.v2
12    .participants("ConversationSid")
13    .list({ limit: 20 });
14
15  participants.forEach((p) => console.log(p.id));
16}
17
18listParticipantByConversation();

Response

1{
2  "meta": {
3    "key": "key",
4    "pageSize": 42,
5    "previousToken": "previousToken",
6    "nextToken": "nextToken"
7  },
8  "participants": [
9    {
10      "id": "id",
11      "conversationId": "conversationId",
12      "accountId": "accountId",
13      "name": "name",
14      "type": "CUSTOMER",
15      "profileId": "profileId",
16      "addresses": [
17        {
18          "channel": "SMS",
19          "address": "address",
20          "channelId": "channelId"
21        }
22      ],
23      "createdAt": "2009-07-06T20:30:00Z",
24      "updatedAt": "2009-07-06T20:30:00Z"
25    }
26  ]
27}

Fetch Participant

GET/v2/Conversations/{ConversationSid}/Participants/{Sid}

Base url: https://conversations.twilio.com (base url)

Retrieve a Participant.

Request

Security: Basic Auth

Path parameters

Property nameTypeRequiredPIIDescription

conversationSidstring

required

sidstring

required

Responses

200400404429500503

OK

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

idstring

Optional

Participant ID.

Example: conv_participant_01k1etx3jbfx88476ccja0889c

conversationIdstring

Optional

Conversation ID.

Example: conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2

accountIdstring

Optional

Account ID.

Example: ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

namestring

Optional

Participant display name.

Example: Dana S.

typeenum<string>

Optional

Type of Participant in the Conversation.

Example: CUSTOMERPossible values:

HUMAN_AGENTCUSTOMERAI_AGENTAGENTUNKNOWN

profileIdstring

Optional

Profile ID. Note: This field is only resolved for CUSTOMER participant types, not for HUMAN_AGENT or AI_AGENT participants.

Example: mem_profile_00000000000000000000000000

addressesarray[object]

Optional

Communication addresses for this Participant. Address format varies by channel:

SMS/VOICE: E.164 phone number (such as "+18005550100")
EMAIL: Email address (such as "user@example.com")
WHATSAPP: Phone number with whatsapp prefix (such as "whatsapp:+18005550100")
RCS: Sender ID or phone number with rcs prefix (such as "rcs:brand_acme_agent" or "rcs:+18005550100")

Show addresses properties

createdAtstring<date-time>

Optional

Timestamp when this Participant was created.

Example: 2023-07-01T12:00:00Z

updatedAtstring<date-time>

Optional

Timestamp when this Participant was last updated.

Example: 2023-07-01T12:00:00Z

Fetch 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.conversations.v2
12    .participants("ConversationSid", "Sid")
13    .fetch();
14
15  console.log(participant.id);
16}
17
18fetchParticipant();

Response

1{
2  "accountId": "ZGkrHSypTsudrGkmdpJJ",
3  "addresses": [
4    {
5      "channel": "SMS",
6      "address": "address",
7      "channelId": "channelId"
8    }
9  ],
10  "conversationId": "conversationId",
11  "createdAt": "2009-07-06T20:30:00Z",
12  "id": "id",
13  "name": "Miss Christine Morgan",
14  "profileId": "profileId",
15  "type": "CUSTOMER",
16  "updatedAt": "2009-07-06T20:30:00Z"
17}

Update a Participant

PUT/v2/Conversations/{ConversationSid}/Participants/{Sid}

Base url: https://conversations.twilio.com (base url)

Update an existing Participant

Request

Security: Basic Auth

Path parameters

Property nameTypeRequiredPIIDescription

conversationSidstring

required

sidstring

required

Request body

Encoding type:application/json

Schema

Property nameTypeRequiredPIIDescriptionChild properties

namestring

Optional

Example: Dana

typeenum<string>

Optional

Possible values:

HUMAN_AGENTCUSTOMERAI_AGENTAGENTUNKNOWN

profileIdstring

Optional

addressesarray[object]

Optional

Show addresses properties

Responses

200400404429500503

OK

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

idstring

Optional

Participant ID.

Example: conv_participant_01k1etx3jbfx88476ccja0889c

conversationIdstring

Optional

Conversation ID.

Example: conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2

accountIdstring

Optional

Account ID.

Example: ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

namestring

Optional

Participant display name.

Example: Dana S.

typeenum<string>

Optional

Type of Participant in the Conversation.

Example: CUSTOMERPossible values:

HUMAN_AGENTCUSTOMERAI_AGENTAGENTUNKNOWN

profileIdstring

Optional

Profile ID. Note: This field is only resolved for CUSTOMER participant types, not for HUMAN_AGENT or AI_AGENT participants.

Example: mem_profile_00000000000000000000000000

addressesarray[object]

Optional

Communication addresses for this Participant. Address format varies by channel:

SMS/VOICE: E.164 phone number (such as "+18005550100")
EMAIL: Email address (such as "user@example.com")
WHATSAPP: Phone number with whatsapp prefix (such as "whatsapp:+18005550100")
RCS: Sender ID or phone number with rcs prefix (such as "rcs:brand_acme_agent" or "rcs:+18005550100")

Show addresses properties

createdAtstring<date-time>

Optional

Timestamp when this Participant was created.

Example: 2023-07-01T12:00:00Z

updatedAtstring<date-time>

Optional

Timestamp when this Participant was last updated.

Example: 2023-07-01T12:00:00Z

Update 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 updateParticipantInConversation() {
11  const participant = await client.conversations.v2
12    .participants("ConversationSid", "Sid")
13    .update({
14      name: "Miss Christine Morgan",
15    });
16
17  console.log(participant.id);
18}
19
20updateParticipantInConversation();

Response

1{
2  "accountId": "ZGkrHSypTsudrGkmdpJJ",
3  "addresses": [
4    {
5      "channel": "SMS",
6      "address": "address",
7      "channelId": "channelId"
8    }
9  ],
10  "conversationId": "conversationId",
11  "createdAt": "2009-07-06T20:30:00Z",
12  "id": "id",
13  "name": "Miss Christine Morgan",
14  "profileId": "profileId",
15  "type": "CUSTOMER",
16  "updatedAt": "2009-07-06T20:30:00Z"
17}