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.

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}