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_00000000000000000000000002

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

metadataobject

Optional

Optional customer-managed key-value metadata for this Conversation. Maximum 8 entries; keys up to 128 characters allowing alphanumeric characters, periods, underscores, and dashes; values up to 512 characters.

Example: {"zendesk_ticket_id":"TKT-456"}Max properties: 8

Show metadata properties

Responses

201400404409429500503

Created

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

idstring

Optional

Conversation ID.

Example: conv_conversation_00000000000000000000000001

accountIdstring

Optional

Account ID.

Example: ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

configurationIdstring

Optional

Configuration ID.

Example: conv_configuration_00000000000000000000000001

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 inquiriesMax length: 512

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

traitExtractionStrategyIdsarray[string]

Optional

A list of Trait Extraction Strategy IDs.

Max items: 1

observationExtractionStrategyIdsarray[string]

Optional

A list of Observation Extraction Strategy IDs.

Max items: 1

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

metadataobject

Optional

Customer-managed key-value metadata for this Conversation.

Example: {"zendesk_ticket_id":"TKT-456"}Max properties: 8

Show metadata properties

participantsarray[object]

Optional

Participants in this Conversation.

Show participants properties

Property nameTypeRequiredPIIDescriptionChild properties

idstring

Optional

Participant ID.

Example: conv_participant_00000000000000000000000001

conversationIdstring

Optional

Conversation ID.

Example: conv_conversation_00000000000000000000000001

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

actionIdstring

Optional

The Action created for the request's action, present only on the create response that dispatched one. Poll GET /v2/Conversations/{ConversationId}/Actions/{ActionId} for its status.

Example: conv_action_00000000000000000000000001

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 at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function createConversationWithConfig() {
14  const conversation = await client.conversations.v2.conversations.create({
15    configurationId: "conv_configuration_00000000000000000000000002",
16  });
17
18  console.log(conversation.id);
19}
20
21createConversationWithConfig();

Response

1{
2  "id": "conv_conversation_00000000000000000000000001",
3  "accountId": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "configurationId": "conv_configuration_00000000000000000000000001",
5  "status": "ACTIVE",
6  "name": "Customer Support - Multi-channel",
7  "createdAt": "2023-07-01T12:00:00Z",
8  "updatedAt": "2023-07-01T12:30:00Z",
9  "metadata": {
10    "zendesk_ticket_id": "TKT-456"
11  }
12}