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.

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
}