Conversations API (v2) - Conversation 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 conversation is a record of interactions between participants. It's the container for all communications that occur during an interaction, including voice calls, SMS messages, and other supported channels.

Endpoints

/v2/Conversations

Create a new Conversation

/v2/Conversations

List Conversations

/v2/Conversations/{Sid}

Fetch Conversation

/v2/Conversations/{Sid}

Update a Conversation

/v2/Conversations/{Sid}

Partially Update a Conversation

/v2/Conversations/{Sid}

Delete a Conversation (async)

Create a new Conversation

POST/v2/Conversations

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

Create a new conversation

Request

Security: Basic Auth

Request body

Encoding type:application/json

Schema

Property nameTypeRequiredPIIDescriptionChild properties

configurationIdstring

required

The ID of an existing configuration.

Example: conv_configuration_01k1etx3jbfx88476ccja0889d

namestring

Optional

The name of the conversation.

Example: Support Chat

configurationobject

Optional

Conversation configuration settings.

Show configuration properties

participantsarray[object]

Optional

Optional list of Participants to create with the Conversation.

Max items: 50

Show participants properties

Responses

201400404409429500503

Created

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

idstring

Optional

Conversation ID.

Example: conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2

accountIdstring

Optional

Account ID.

Example: ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

configurationIdstring

Optional

Configuration ID.

Example: conv_configuration_01k1etk2y5f1y9fpe2epfdtvv2

statusenum<string>

Optional

Conversation status.

Example: ACTIVEPossible values:

ACTIVEINACTIVECLOSED

namestring

Optional

Conversation name.

Example: Customer Support Chat

createdAtstring<date-time>

Optional

Timestamp when this Conversation was created.

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

updatedAtstring<date-time>

Optional

Timestamp when this Conversation was last updated.

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

configurationobject

Optional

Full configuration settings for this Conversation.

Show configuration properties

Property nameTypeRequiredPIIDescriptionChild properties

displayNamestring

Optional

A human-readable name for the configuration. Limited to 32 characters.

Example: My Support ConfigPattern: ^[a-zA-Z0-9-_ ]+$Max length: 32

descriptionstring

Optional

Human-readable description for the Configuration.

Example: Customer Support Configuration for handling all inbound customer inquiries

conversationGroupingTypeenum<string>

Optional

Type of Conversation grouping strategy:

GROUP_BY_PROFILE: Groups Communications by resolved Profile from the Memory Store. A Profile is looked up or created for CUSTOMER Participant types. All Communications from the same Profile are in the same Conversation, regardless of address or channel.
GROUP_BY_PARTICIPANT_ADDRESSES: Groups Communications by Participant addresses across all channels. A customer using +18005550100 will be in the same Conversation whether they contact by SMS, WhatsApp, or RCS.
GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE: Groups Communications by both Participant addresses AND channel. A customer using +18005550100 by SMS will be in a different Conversation than the same customer by Voice.

Example: GROUP_BY_PROFILEPossible values:

GROUP_BY_PROFILEGROUP_BY_PARTICIPANT_ADDRESSESGROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE

memoryStoreIdstring

Optional

Memory Store ID for Profile resolution.

Example: mem_store_01k1etk2y5f1y9fpe2epfdtvv2

channelSettingsobject

Optional

Channel-specific parameters forwarded as-is to the downstream sending service. Allows passing backend-specific fields without requiring API changes.

Example: {"messagingServiceSid":"MG1234567890abcdef1234567890abcdef","statusCallback":"https://example.com/status"}

Show channelSettings properties

statusCallbacksarray[object]

Optional

List of default webhook configurations applied to Conversations under this Configuration.

Max items: 20

Show statusCallbacks properties

intelligenceConfigurationIdsarray[string]

Optional

List of Intelligence Configuration IDs configured for this Configuration.

Example: ["agent1","agent2"]Max items: 5

memoryExtractionEnabledboolean

Optional

Whether memory extraction is enabled for conversations under this configuration. Defaults to false.

Default: falseExample: false

conversationsV1Bridgeobject

Optional

Configuration for Conversations V1 bridge. When set, messaging channels route through Conversations V1. Use this to integrate with existing Conversations V1 applications.

Example: {"serviceId":"IS00000000000000000000000000000000"}

Show conversationsV1Bridge properties

participantsarray[object]

Optional

Participants in this Conversation.

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

Create a new Conversation

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 createConversationWithConfig() {
11  const conversation = await client.conversations.v2.conversations.create({
12    configurationId: "configurationId",
13  });
14
15  console.log(conversation.id);
16}
17
18createConversationWithConfig();

Response

1{
2  "accountId": "ZGkrHSypTsudrGkmdpJJ",
3  "configuration": {
4    "displayName": "My Support Config",
5    "description": "description",
6    "conversationGroupingType": "GROUP_BY_PROFILE",
7    "memoryStoreId": "memoryStoreId",
8    "channelSettings": {},
9    "statusCallbacks": [
10      {
11        "url": "https://www.example.com",
12        "method": "POST"
13      }
14    ],
15    "intelligenceConfigurationIds": [
16      "intelligenceConfigurationIds"
17    ],
18    "memoryExtractionEnabled": false,
19    "conversationsV1Bridge": {
20      "serviceId": "IS00000000000000000000000000000000"
21    }
22  },
23  "configurationId": "configurationId",
24  "createdAt": "2009-07-06T20:30:00Z",
25  "id": "id",
26  "name": "Miss Christine Morgan",
27  "participants": [
28    {
29      "id": "id",
30      "conversationId": "conversationId",
31      "accountId": "accountId",
32      "name": "name",
33      "type": "CUSTOMER",
34      "profileId": "profileId",
35      "addresses": [
36        {
37          "channel": "SMS",
38          "address": "address",
39          "channelId": "channelId"
40        }
41      ],
42      "createdAt": "2009-07-06T20:30:00Z",
43      "updatedAt": "2009-07-06T20:30:00Z"
44    }
45  ],
46  "status": "ACTIVE",
47  "updatedAt": "2009-07-06T20:30:00Z"
48}

List Conversations

GET/v2/Conversations

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

Retrieve a list of Conversations.

Request

Security: Basic Auth

Query string

Property nameTypeRequiredPIIDescription

statusarray[enum<string>]

Optional

Filters for specific statuses

Possible values:

ACTIVEINACTIVECLOSED

channelIdstring

Optional

The resource identifier (such as callSid or messageSid) to filter conversations.

pageSizeinteger

Optional

Maximum number of items to return in a single response

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

pageTokenstring

Optional

A URL-safe, base64-encoded token representing the page of results to return

Example: eyJwYWdlIjoyLCJxdWVyeSI6ImJvb2tzIn0=

Responses

200400404429500503

OK

Schema

Property nameTypeRequiredPIIDescriptionChild properties

conversationsarray[object]

Optional

Min items: 0

Show conversations properties

Property nameTypeRequiredPIIDescriptionChild properties

idstring

Optional

Conversation ID.

Example: conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2

accountIdstring

Optional

Account ID.

Example: ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

configurationIdstring

Optional

Configuration ID.

Example: conv_configuration_01k1etk2y5f1y9fpe2epfdtvv2

statusenum<string>

Optional

Conversation status.

Example: ACTIVEPossible values:

ACTIVEINACTIVECLOSED

namestring

Optional

Conversation name.

Example: Customer Support Chat

createdAtstring<date-time>

Optional

Timestamp when this Conversation was created.

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

updatedAtstring<date-time>

Optional

Timestamp when this Conversation was last updated.

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

configurationobject

Optional

Full configuration settings for this Conversation.

Show configuration properties

Property nameTypeRequiredPIIDescriptionChild properties

displayNamestring

Optional

A human-readable name for the configuration. Limited to 32 characters.

Example: My Support ConfigPattern: ^[a-zA-Z0-9-_ ]+$Max length: 32

descriptionstring

Optional

Human-readable description for the Configuration.

Example: Customer Support Configuration for handling all inbound customer inquiries

conversationGroupingTypeenum<string>

Optional

Type of Conversation grouping strategy:

GROUP_BY_PROFILE: Groups Communications by resolved Profile from the Memory Store. A Profile is looked up or created for CUSTOMER Participant types. All Communications from the same Profile are in the same Conversation, regardless of address or channel.
GROUP_BY_PARTICIPANT_ADDRESSES: Groups Communications by Participant addresses across all channels. A customer using +18005550100 will be in the same Conversation whether they contact by SMS, WhatsApp, or RCS.
GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE: Groups Communications by both Participant addresses AND channel. A customer using +18005550100 by SMS will be in a different Conversation than the same customer by Voice.

Example: GROUP_BY_PROFILEPossible values:

GROUP_BY_PROFILEGROUP_BY_PARTICIPANT_ADDRESSESGROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE

memoryStoreIdstring

Optional

Memory Store ID for Profile resolution.

Example: mem_store_01k1etk2y5f1y9fpe2epfdtvv2

channelSettingsobject

Optional

Channel-specific parameters forwarded as-is to the downstream sending service. Allows passing backend-specific fields without requiring API changes.

Example: {"messagingServiceSid":"MG1234567890abcdef1234567890abcdef","statusCallback":"https://example.com/status"}

Show channelSettings properties

statusCallbacksarray[object]

Optional

List of default webhook configurations applied to Conversations under this Configuration.

Max items: 20

Show statusCallbacks properties

intelligenceConfigurationIdsarray[string]

Optional

List of Intelligence Configuration IDs configured for this Configuration.

Example: ["agent1","agent2"]Max items: 5

memoryExtractionEnabledboolean

Optional

Whether memory extraction is enabled for conversations under this configuration. Defaults to false.

Default: falseExample: false

conversationsV1Bridgeobject

Optional

Configuration for Conversations V1 bridge. When set, messaging channels route through Conversations V1. Use this to integrate with existing Conversations V1 applications.

Example: {"serviceId":"IS00000000000000000000000000000000"}

Show conversationsV1Bridge properties

participantsarray[object]

Optional

Participants in this Conversation.

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 Conversations

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

Response

1{
2  "conversations": [
3    {
4      "id": "id",
5      "accountId": "accountId",
6      "configurationId": "configurationId",
7      "status": "ACTIVE",
8      "name": "name",
9      "createdAt": "2009-07-06T20:30:00Z",
10      "updatedAt": "2009-07-06T20:30:00Z",
11      "configuration": {
12        "displayName": "My Support Config",
13        "description": "description",
14        "conversationGroupingType": "GROUP_BY_PROFILE",
15        "memoryStoreId": "memoryStoreId",
16        "channelSettings": {},
17        "statusCallbacks": [
18          {
19            "url": "https://www.example.com",
20            "method": "POST"
21          }
22        ],
23        "intelligenceConfigurationIds": [
24          "intelligenceConfigurationIds"
25        ],
26        "memoryExtractionEnabled": false,
27        "conversationsV1Bridge": {
28          "serviceId": "IS00000000000000000000000000000000"
29        }
30      },
31      "participants": [
32        {
33          "id": "id",
34          "conversationId": "conversationId",
35          "accountId": "accountId",
36          "name": "name",
37          "type": "CUSTOMER",
38          "profileId": "profileId",
39          "addresses": [
40            {
41              "channel": "SMS",
42              "address": "address",
43              "channelId": "channelId"
44            }
45          ],
46          "createdAt": "2009-07-06T20:30:00Z",
47          "updatedAt": "2009-07-06T20:30:00Z"
48        }
49      ]
50    }
51  ],
52  "meta": {
53    "key": "key",
54    "pageSize": 20,
55    "previousToken": "previousToken",
56    "nextToken": "nextToken"
57  }
58}

Fetch Conversation

GET/v2/Conversations/{Sid}

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

Retrieve a Conversation.

Request

Security: Basic Auth

Path parameters

Property nameTypeRequiredPIIDescription

sidstring

required

Responses

200400404429500503

OK

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

idstring

Optional

Conversation ID.

Example: conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2

accountIdstring

Optional

Account ID.

Example: ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

configurationIdstring

Optional

Configuration ID.

Example: conv_configuration_01k1etk2y5f1y9fpe2epfdtvv2

statusenum<string>

Optional

Conversation status.

Example: ACTIVEPossible values:

ACTIVEINACTIVECLOSED

namestring

Optional

Conversation name.

Example: Customer Support Chat

createdAtstring<date-time>

Optional

Timestamp when this Conversation was created.

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

updatedAtstring<date-time>

Optional

Timestamp when this Conversation was last updated.

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

configurationobject

Optional

Full configuration settings for this Conversation.

Show configuration properties

Property nameTypeRequiredPIIDescriptionChild properties

displayNamestring

Optional

A human-readable name for the configuration. Limited to 32 characters.

Example: My Support ConfigPattern: ^[a-zA-Z0-9-_ ]+$Max length: 32

descriptionstring

Optional

Human-readable description for the Configuration.

Example: Customer Support Configuration for handling all inbound customer inquiries

conversationGroupingTypeenum<string>

Optional

Type of Conversation grouping strategy:

GROUP_BY_PROFILE: Groups Communications by resolved Profile from the Memory Store. A Profile is looked up or created for CUSTOMER Participant types. All Communications from the same Profile are in the same Conversation, regardless of address or channel.
GROUP_BY_PARTICIPANT_ADDRESSES: Groups Communications by Participant addresses across all channels. A customer using +18005550100 will be in the same Conversation whether they contact by SMS, WhatsApp, or RCS.
GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE: Groups Communications by both Participant addresses AND channel. A customer using +18005550100 by SMS will be in a different Conversation than the same customer by Voice.

Example: GROUP_BY_PROFILEPossible values:

GROUP_BY_PROFILEGROUP_BY_PARTICIPANT_ADDRESSESGROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE

memoryStoreIdstring

Optional

Memory Store ID for Profile resolution.

Example: mem_store_01k1etk2y5f1y9fpe2epfdtvv2

channelSettingsobject

Optional

Channel-specific parameters forwarded as-is to the downstream sending service. Allows passing backend-specific fields without requiring API changes.

Example: {"messagingServiceSid":"MG1234567890abcdef1234567890abcdef","statusCallback":"https://example.com/status"}

Show channelSettings properties

statusCallbacksarray[object]

Optional

List of default webhook configurations applied to Conversations under this Configuration.

Max items: 20

Show statusCallbacks properties

intelligenceConfigurationIdsarray[string]

Optional

List of Intelligence Configuration IDs configured for this Configuration.

Example: ["agent1","agent2"]Max items: 5

memoryExtractionEnabledboolean

Optional

Whether memory extraction is enabled for conversations under this configuration. Defaults to false.

Default: falseExample: false

conversationsV1Bridgeobject

Optional

Configuration for Conversations V1 bridge. When set, messaging channels route through Conversations V1. Use this to integrate with existing Conversations V1 applications.

Example: {"serviceId":"IS00000000000000000000000000000000"}

Show conversationsV1Bridge properties

participantsarray[object]

Optional

Participants in this Conversation.

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

Fetch Conversation

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 fetchConversation() {
11  const conversation = await client.conversations.v2
12    .conversations("Sid")
13    .fetch();
14
15  console.log(conversation.id);
16}
17
18fetchConversation();

Response

1{
2  "accountId": "ZGkrHSypTsudrGkmdpJJ",
3  "configuration": {
4    "displayName": "My Support Config",
5    "description": "description",
6    "conversationGroupingType": "GROUP_BY_PROFILE",
7    "memoryStoreId": "memoryStoreId",
8    "channelSettings": {},
9    "statusCallbacks": [
10      {
11        "url": "https://www.example.com",
12        "method": "POST"
13      }
14    ],
15    "intelligenceConfigurationIds": [
16      "intelligenceConfigurationIds"
17    ],
18    "memoryExtractionEnabled": false,
19    "conversationsV1Bridge": {
20      "serviceId": "IS00000000000000000000000000000000"
21    }
22  },
23  "configurationId": "configurationId",
24  "createdAt": "2009-07-06T20:30:00Z",
25  "id": "id",
26  "name": "Miss Christine Morgan",
27  "participants": [
28    {
29      "id": "id",
30      "conversationId": "conversationId",
31      "accountId": "accountId",
32      "name": "name",
33      "type": "CUSTOMER",
34      "profileId": "profileId",
35      "addresses": [
36        {
37          "channel": "SMS",
38          "address": "address",
39          "channelId": "channelId"
40        }
41      ],
42      "createdAt": "2009-07-06T20:30:00Z",
43      "updatedAt": "2009-07-06T20:30:00Z"
44    }
45  ],
46  "status": "ACTIVE",
47  "updatedAt": "2009-07-06T20:30:00Z"
48}

Update a Conversation

PUT/v2/Conversations/{Sid}

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

Update an existing conversation

Request

Security: Basic Auth

Path parameters

Property nameTypeRequiredPIIDescription

sidstring

required

Request body

Encoding type:application/json

Schema

Property nameTypeRequiredPIIDescriptionChild properties

namestring

Optional

The name of the Conversation.

Example: Support Chat

statusenum<string>

required

The state of the Conversation.

Possible values:

ACTIVEINACTIVECLOSED

Responses

200400404429500503

OK

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

idstring

Optional

Conversation ID.

Example: conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2

accountIdstring

Optional

Account ID.

Example: ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

configurationIdstring

Optional

Configuration ID.

Example: conv_configuration_01k1etk2y5f1y9fpe2epfdtvv2

statusenum<string>

Optional

Conversation status.

Example: ACTIVEPossible values:

ACTIVEINACTIVECLOSED

namestring

Optional

Conversation name.

Example: Customer Support Chat

createdAtstring<date-time>

Optional

Timestamp when this Conversation was created.

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

updatedAtstring<date-time>

Optional

Timestamp when this Conversation was last updated.

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

configurationobject

Optional

Full configuration settings for this Conversation.

Show configuration properties

Property nameTypeRequiredPIIDescriptionChild properties

displayNamestring

Optional

A human-readable name for the configuration. Limited to 32 characters.

Example: My Support ConfigPattern: ^[a-zA-Z0-9-_ ]+$Max length: 32

descriptionstring

Optional

Human-readable description for the Configuration.

Example: Customer Support Configuration for handling all inbound customer inquiries

conversationGroupingTypeenum<string>

Optional

Type of Conversation grouping strategy:

GROUP_BY_PROFILE: Groups Communications by resolved Profile from the Memory Store. A Profile is looked up or created for CUSTOMER Participant types. All Communications from the same Profile are in the same Conversation, regardless of address or channel.
GROUP_BY_PARTICIPANT_ADDRESSES: Groups Communications by Participant addresses across all channels. A customer using +18005550100 will be in the same Conversation whether they contact by SMS, WhatsApp, or RCS.
GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE: Groups Communications by both Participant addresses AND channel. A customer using +18005550100 by SMS will be in a different Conversation than the same customer by Voice.

Example: GROUP_BY_PROFILEPossible values:

GROUP_BY_PROFILEGROUP_BY_PARTICIPANT_ADDRESSESGROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE

memoryStoreIdstring

Optional

Memory Store ID for Profile resolution.

Example: mem_store_01k1etk2y5f1y9fpe2epfdtvv2

channelSettingsobject

Optional

Channel-specific parameters forwarded as-is to the downstream sending service. Allows passing backend-specific fields without requiring API changes.

Example: {"messagingServiceSid":"MG1234567890abcdef1234567890abcdef","statusCallback":"https://example.com/status"}

Show channelSettings properties

statusCallbacksarray[object]

Optional

List of default webhook configurations applied to Conversations under this Configuration.

Max items: 20

Show statusCallbacks properties

intelligenceConfigurationIdsarray[string]

Optional

List of Intelligence Configuration IDs configured for this Configuration.

Example: ["agent1","agent2"]Max items: 5

memoryExtractionEnabledboolean

Optional

Whether memory extraction is enabled for conversations under this configuration. Defaults to false.

Default: falseExample: false

conversationsV1Bridgeobject

Optional

Configuration for Conversations V1 bridge. When set, messaging channels route through Conversations V1. Use this to integrate with existing Conversations V1 applications.

Example: {"serviceId":"IS00000000000000000000000000000000"}

Show conversationsV1Bridge properties

participantsarray[object]

Optional

Participants in this Conversation.

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

Update a Conversation

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 updateConversationById() {
11  const conversation = await client.conversations.v2
12    .conversations("Sid")
13    .update({
14      status: "ACTIVE",
15    });
16
17  console.log(conversation.id);
18}
19
20updateConversationById();

Response

1{
2  "accountId": "ZGkrHSypTsudrGkmdpJJ",
3  "configuration": {
4    "displayName": "My Support Config",
5    "description": "description",
6    "conversationGroupingType": "GROUP_BY_PROFILE",
7    "memoryStoreId": "memoryStoreId",
8    "channelSettings": {},
9    "statusCallbacks": [
10      {
11        "url": "https://www.example.com",
12        "method": "POST"
13      }
14    ],
15    "intelligenceConfigurationIds": [
16      "intelligenceConfigurationIds"
17    ],
18    "memoryExtractionEnabled": false,
19    "conversationsV1Bridge": {
20      "serviceId": "IS00000000000000000000000000000000"
21    }
22  },
23  "configurationId": "configurationId",
24  "createdAt": "2009-07-06T20:30:00Z",
25  "id": "id",
26  "name": "Miss Christine Morgan",
27  "participants": [
28    {
29      "id": "id",
30      "conversationId": "conversationId",
31      "accountId": "accountId",
32      "name": "name",
33      "type": "CUSTOMER",
34      "profileId": "profileId",
35      "addresses": [
36        {
37          "channel": "SMS",
38          "address": "address",
39          "channelId": "channelId"
40        }
41      ],
42      "createdAt": "2009-07-06T20:30:00Z",
43      "updatedAt": "2009-07-06T20:30:00Z"
44    }
45  ],
46  "status": "ACTIVE",
47  "updatedAt": "2009-07-06T20:30:00Z"
48}

Partially Update a Conversation

PATCH/v2/Conversations/{Sid}

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

Partially update the details of an existing Conversation.

Request

Security: Basic Auth

Path parameters

Property nameTypeRequiredPIIDescription

sidstring

required

Request body

Encoding type:application/json

Schema

Property nameTypeRequiredPIIDescriptionChild properties

namestring

Optional

The name of the Conversation.

Example: Support Chat

statusenum<string>

Optional

The state of the Conversation.

Possible values:

ACTIVEINACTIVECLOSED

configurationobject

Optional

Partial configuration update for an existing conversation. Only statusCallbacks can be modified.

Show configuration properties

Responses

200400404429500503

OK

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

idstring

Optional

Conversation ID.

Example: conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2

accountIdstring

Optional

Account ID.

Example: ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

configurationIdstring

Optional

Configuration ID.

Example: conv_configuration_01k1etk2y5f1y9fpe2epfdtvv2

statusenum<string>

Optional

Conversation status.

Example: ACTIVEPossible values:

ACTIVEINACTIVECLOSED

namestring

Optional

Conversation name.

Example: Customer Support Chat

createdAtstring<date-time>

Optional

Timestamp when this Conversation was created.

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

updatedAtstring<date-time>

Optional

Timestamp when this Conversation was last updated.

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

configurationobject

Optional

Full configuration settings for this Conversation.

Show configuration properties

Property nameTypeRequiredPIIDescriptionChild properties

displayNamestring

Optional

A human-readable name for the configuration. Limited to 32 characters.

Example: My Support ConfigPattern: ^[a-zA-Z0-9-_ ]+$Max length: 32

descriptionstring

Optional

Human-readable description for the Configuration.

Example: Customer Support Configuration for handling all inbound customer inquiries

conversationGroupingTypeenum<string>

Optional

Type of Conversation grouping strategy:

GROUP_BY_PROFILE: Groups Communications by resolved Profile from the Memory Store. A Profile is looked up or created for CUSTOMER Participant types. All Communications from the same Profile are in the same Conversation, regardless of address or channel.
GROUP_BY_PARTICIPANT_ADDRESSES: Groups Communications by Participant addresses across all channels. A customer using +18005550100 will be in the same Conversation whether they contact by SMS, WhatsApp, or RCS.
GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE: Groups Communications by both Participant addresses AND channel. A customer using +18005550100 by SMS will be in a different Conversation than the same customer by Voice.

Example: GROUP_BY_PROFILEPossible values:

GROUP_BY_PROFILEGROUP_BY_PARTICIPANT_ADDRESSESGROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE

memoryStoreIdstring

Optional

Memory Store ID for Profile resolution.

Example: mem_store_01k1etk2y5f1y9fpe2epfdtvv2

channelSettingsobject

Optional

Channel-specific parameters forwarded as-is to the downstream sending service. Allows passing backend-specific fields without requiring API changes.

Example: {"messagingServiceSid":"MG1234567890abcdef1234567890abcdef","statusCallback":"https://example.com/status"}

Show channelSettings properties

statusCallbacksarray[object]

Optional

List of default webhook configurations applied to Conversations under this Configuration.

Max items: 20

Show statusCallbacks properties

intelligenceConfigurationIdsarray[string]

Optional

List of Intelligence Configuration IDs configured for this Configuration.

Example: ["agent1","agent2"]Max items: 5

memoryExtractionEnabledboolean

Optional

Whether memory extraction is enabled for conversations under this configuration. Defaults to false.

Default: falseExample: false

conversationsV1Bridgeobject

Optional

Configuration for Conversations V1 bridge. When set, messaging channels route through Conversations V1. Use this to integrate with existing Conversations V1 applications.

Example: {"serviceId":"IS00000000000000000000000000000000"}

Show conversationsV1Bridge properties

participantsarray[object]

Optional

Participants in this Conversation.

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

Partially Update a Conversation

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

Response

1{
2  "accountId": "ZGkrHSypTsudrGkmdpJJ",
3  "configuration": {
4    "displayName": "My Support Config",
5    "description": "description",
6    "conversationGroupingType": "GROUP_BY_PROFILE",
7    "memoryStoreId": "memoryStoreId",
8    "channelSettings": {},
9    "statusCallbacks": [
10      {
11        "url": "https://www.example.com",
12        "method": "POST"
13      }
14    ],
15    "intelligenceConfigurationIds": [
16      "intelligenceConfigurationIds"
17    ],
18    "memoryExtractionEnabled": false,
19    "conversationsV1Bridge": {
20      "serviceId": "IS00000000000000000000000000000000"
21    }
22  },
23  "configurationId": "configurationId",
24  "createdAt": "2009-07-06T20:30:00Z",
25  "id": "id",
26  "name": "Miss Christine Morgan",
27  "participants": [
28    {
29      "id": "id",
30      "conversationId": "conversationId",
31      "accountId": "accountId",
32      "name": "name",
33      "type": "CUSTOMER",
34      "profileId": "profileId",
35      "addresses": [
36        {
37          "channel": "SMS",
38          "address": "address",
39          "channelId": "channelId"
40        }
41      ],
42      "createdAt": "2009-07-06T20:30:00Z",
43      "updatedAt": "2009-07-06T20:30:00Z"
44    }
45  ],
46  "status": "ACTIVE",
47  "updatedAt": "2009-07-06T20:30:00Z"
48}

Delete a Conversation (async)

DELETE/v2/Conversations/{Sid}

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

Asynchronously delete a conversation and all associated data. Returns 202 Accepted with an Operation-Id for status tracking via GET /v2/ControlPlane/Operations/{operationId}.

Request

Security: Basic Auth

Headers

Property nameTypeRequiredPIIDescription

idempotency-Keystring

Optional

Client-generated UUID key to ensure idempotent behavior. Submitting the same key returns the original response without creating a duplicate operation. Keys are scoped to account + region with a 24-hour TTL.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Path parameters

Property nameTypeRequiredPIIDescription

sidstring

required

Responses

202400404409429500503

Operation accepted for asynchronous processing

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

statusUrlstring<uri>

Optional

URL to poll for operation status.

Example: https://conversations.twilio.com/v2/ControlPlane/Operations/proc_job_01h9d8r0vte3hz8tykdj329t7r

relatedobject

Optional

Named resource identifiers associated with this operation. Keys depend on the operation type:

config-create, config-update, config-delete: configurationId
conversation-delete: conversationId

Example: {"configurationId":"cfg_configuration_01h9d8r0vte3hz8tykdj329t7r"}

Show related properties

Delete a Conversation (async)

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 deleteConversationAsync() {
11  await client.conversations.v2.conversations("Sid").remove();
12}
13
14deleteConversationAsync();

Response

1{
2  "related": {},
3  "statusUrl": "https://www.example.com"
4}