Create a new Conversation

(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.

POST/v2/Conversations

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

Create a new conversation

Request

Authentication

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}