Skip to contentSkip to navigationSkip to topbar
Twilio Docs

Conversations API (v2) - Configuration 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(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.

Overview

overview page anchor

A conversation configuration is the top-level object in Conversation Orchestrator. It contains the settings that define how Conversation Orchestrator captures traffic and connects to other services.

Endpoints

Create a Configuration

create-configuration page anchor

POST/v2/ControlPlane/Configurations

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

Create a new Configuration

Request

create-configuration-request 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
}

List Configurations

list-configuration page anchor

GET/v2/ControlPlane/Configurations

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

Retrieve a list of Configurations.

Request

list-configuration-request page anchor

Query string

list-configuration-query-string page anchor
Property nameTypeRequiredPIIDescription
pageSizeinteger

Optional

Not PII

Maximum number of items to return in a single response

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

Optional

Not PII

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

Example: eyJwYWdlIjoyLCJxdWVyeSI6ImJvb2tzIn0=
memoryStoreIdstring

Optional

Not PII

Filter configurations by Memory Store ID

Example: mem_store_01k1etk2y5f1y9fpe2epfdtvv2Pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$

Responses

list-configuration-responses page anchor
200400404429500503

OK

Schema
Property nameTypeRequiredPIIDescriptionChild properties
configurationsarray[object]

Optional

Not PII
Min items: 0
metaobject

Optional

Not PII
List ConfigurationsLink to code sample: List Configurations
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 listConfiguration() {

11
  const configurations = await client.conversations.v2.configurations.list({

12
    limit: 20,

13
  });

14


15
  configurations.forEach((c) => console.log(c.id));

16
}

17


18
listConfiguration();

Response

Note about this response
1
{

2
  "configurations": [

3
    {

4
      "id": "id",

5
      "displayName": "My Support Config",

6
      "description": "description",

7
      "conversationGroupingType": "GROUP_BY_PROFILE",

8
      "memoryStoreId": "memoryStoreId",

9
      "channelSettings": {},

10
      "statusCallbacks": [

11
        {

12
          "url": "https://www.example.com",

13
          "method": "POST"

14
        }

15
      ],

16
      "intelligenceConfigurationIds": [

17
        "intelligenceConfigurationIds"

18
      ],

19
      "memoryExtractionEnabled": false,

20
      "conversationsV1Bridge": {

21
        "serviceId": "IS00000000000000000000000000000000"

22
      },

23
      "createdAt": "2009-07-06T20:30:00Z",

24
      "updatedAt": "2009-07-06T20:30:00Z",

25
      "version": 1

26
    }

27
  ],

28
  "meta": {

29
    "key": "key",

30
    "pageSize": 20,

31
    "previousToken": "previousToken",

32
    "nextToken": "nextToken"

33
  }

34
}

Fetch Configuration

fetch-configuration page anchor

GET/v2/ControlPlane/Configurations/{Sid}

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

Retrieve a Configuration.

Request

fetch-configuration-request page anchor

Path parameters

fetch-configuration-path-parameters page anchor
Property nameTypeRequiredPIIDescription
sidstring
required
Not PII

Responses

fetch-configuration-responses page anchor
200404429500503

OK

SchemaExample
Property nameTypeRequiredPIIDescriptionChild properties
idstring

Optional

Not PII

Configuration ID.

Example: conv_configuration_01k1etk2y5f1y9fpe2epfdtvv2
displayNamestring

Optional

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

Optional

Not PII

Human-readable description for the Configuration. Allows spaces and special characters, typically limited to a paragraph of text. This serves as a descriptive field rather than just a name.

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

Optional

Not PII

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

Not PII

Memory Store ID for Profile resolution.

Example: mem_store_01k1etk2y5f1y9fpe2epfdtvv2
channelSettingsobject

Optional

Not PII

Channel-specific configuration settings including timeout settings and capture rules.

Example: {"SMS":{"statusTimeouts":{"inactive":10,"closed":15},"captureRules":[{"from":"+18005550100","to":"+18005550101","metadata":{}},{"from":"+18005550103","to":"*","metadata":{}},{"from":"*","to":"+18005550103","metadata":{}}]},"VOICE":{"statusTimeouts":{"inactive":5,"closed":30},"captureRules":[{"from":"+18005550104","to":"+18005550105","metadata":{"callType":"PSTN"}},{"from":"+18005550106","to":"*","metadata":{}},{"from":"*","to":"+18005550106","metadata":{}}]},"WHATSAPP":{"statusTimeouts":{"inactive":15,"closed":60},"captureRules":[{"from":"whatsapp:+18005550100","to":"*","metadata":{}},{"from":"*","to":"whatsapp:+18005550100","metadata":{}}]},"RCS":{"statusTimeouts":{"inactive":15,"closed":60},"captureRules":[{"from":"rcs:brand_acme_agent","to":"*","metadata":{}},{"from":"*","to":"rcs:brand_acme_agent","metadata":{}},{"from":"rcs:+18005550107","to":"*","metadata":{}}]},"CHAT":{"statusTimeouts":{"inactive":15,"closed":60},"captureRules":[{"from":"*","to":"*","metadata":{"chatService":"IS00000000000000000000000000000000"}}]}}
statusCallbacksarray[object]

Optional

Not PII

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

Max items: 20
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
conversationsV1Bridgeobject

Optional

Not PII

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"}
createdAtstring<date-time>
read-only

Optional

Not PII

Timestamp when this Configuration was created.

Example: 2023-10-14T10:30:00Z
updatedAtstring<date-time>
read-only

Optional

Not PII

Timestamp when this Configuration was last updated.

Example: 2023-10-14T15:45:30Z
versioninteger<int64>
read-only

Optional

Not PII

Version number used for optimistic locking.

Example: 1
Fetch ConfigurationLink to code sample: Fetch 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 fetchConfiguration() {

11
  const configuration = await client.conversations.v2

12
    .configurations("Sid")

13
    .fetch();

14


15
  console.log(configuration.id);

16
}

17


18
fetchConfiguration();

Response

Note about this response
1
{

2
  "channelSettings": {},

3
  "conversationGroupingType": "GROUP_BY_PROFILE",

4
  "conversationsV1Bridge": {

5
    "serviceId": "IS00000000000000000000000000000000"

6
  },

7
  "createdAt": "2009-07-06T20:30:00Z",

8
  "description": "description",

9
  "displayName": "My Support Config",

10
  "id": "id",

11
  "intelligenceConfigurationIds": [

12
    "intelligenceConfigurationIds"

13
  ],

14
  "memoryExtractionEnabled": false,

15
  "memoryStoreId": "memoryStoreId",

16
  "statusCallbacks": [

17
    {

18
      "url": "https://www.example.com",

19
      "method": "POST"

20
    }

21
  ],

22
  "updatedAt": "2009-07-06T20:30:00Z",

23
  "version": 1

24
}

Update Configuration

update-configuration page anchor

PUT/v2/ControlPlane/Configurations/{Sid}

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

Update an existing Configuration

Request

update-configuration-request page anchor

Headers

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

Path parameters

update-configuration-path-parameters page anchor
Property nameTypeRequiredPIIDescription
sidstring
required
Not PII

Request body

update-configuration-request-body page anchor
Encoding type:application/json
Schema
Property nameTypeRequiredPIIDescriptionChild properties
displayNamestring

Optional

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: Updated Customer Support Configuration
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 for profile resolution.

Example: memora_service_123
channelSettingsobject
required
Not PII
statusCallbacksarray[object]

Optional

Not PII
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

update-configuration-responses page anchor
202400404409429500503

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"}
Update ConfigurationLink to code sample: Update 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 updateConfiguration() {

11
  const configuration = await client.conversations.v2

12
    .configurations("Sid")

13
    .update({

14
      description: "description",

15
      conversationGroupingType: "GROUP_BY_PROFILE",

16
      memoryStoreId: "memoryStoreId",

17
      channelSettings: {},

18
    });

19


20
  console.log(configuration.statusUrl);

21
}

22


23
updateConfiguration();

Response

Note about this response
1
{

2
  "related": {},

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

4
}

Delete Configuration

delete-configuration page anchor

DELETE/v2/ControlPlane/Configurations/{Sid}

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

Delete a Configuration

Request

delete-configuration-request page anchor

Headers

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

Path parameters

delete-configuration-path-parameters page anchor
Property nameTypeRequiredPIIDescription
sidstring
required
Not PII

Responses

delete-configuration-responses page anchor
202404409429500503

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"}
Delete ConfigurationLink to code sample: Delete 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 deleteConfiguration() {

11
  await client.conversations.v2.configurations("Sid").remove();

12
}

13


14
deleteConfiguration();

Response

Note about this response
1
{

2
  "related": {},

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

4
}