Skip to contentSkip to navigationSkip to topbar
Twilio Docs

Create a Configuration

(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(link takes you to an external page). 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(link takes you to an external page). If your account hasn't been migrated, you'll be redirected to the legacy Console where these products won't appear.

POST/v2/ControlPlane/Configurations

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

Create a new Configuration

Request

create-configuration-request page anchor

Authentication

authentication page anchor

Headers

create-configuration-headers page anchor
Property nameTypeRequiredPIIDescription
idempotency-Keystring

Optional

Not PII

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

Request body

create-configuration-request-body page anchor
Encoding type:application/json
Schema
Property nameTypeRequiredPIIDescriptionChild properties
displayNamestring
required
Not PII

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

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

Human-readable description for the configuration.

Example: Customer Support Configuration for handling all inbound customer inquiries
conversationGroupingTypeenum<string>
required
Not PII

The strategy Conversation Orchestrator uses to assign communications to conversations.

Example: GROUP_BY_PROFILEPossible values:
GROUP_BY_PROFILEGROUP_BY_PARTICIPANT_ADDRESSESGROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE
memoryStoreIdstring
required
Not PII

The memory store ID that Conversation Orchestrator uses for profile resolution.

Example: memora_service_123
channelSettingsobject

Optional

Not PII
statusCallbacksarray[object]

Optional

Not PII

A list of webhook configurations.

Max items: 2
intelligenceConfigurationIdsarray[string]

Optional

Not PII

A list of Conversational Intelligence configuration IDs.

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

Optional

Not PII

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

Default: falseExample: false

Responses

create-configuration-responses page anchor
202400409429500503

Accepted - Operation created for asynchronous processing

SchemaExample
Property nameTypeRequiredPIIDescriptionChild properties
statusUrlstring<uri>

Optional

Not PII

URL to poll for operation status.

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

Optional

Not PII

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"}
Create a ConfigurationLink to code sample: Create a Configuration
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const 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

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function createConfiguration() {

11
  const configuration = await client.conversations.v2.configurations.create({

12
    displayName: "My Support Config",

13
    description: "description",

14
    conversationGroupingType: "GROUP_BY_PROFILE",

15
    memoryStoreId: "memoryStoreId",

16
  });

17


18
  console.log(configuration.statusUrl);

19
}

20


21
createConfiguration();

Response

Note about this response
1
{

2
  "related": {},

3
  "statusUrl": "https://www.example.com"

4
}