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.

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 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}