Skip to contentSkip to navigationSkip to topbar
Page toolsOn this page
Looking for more inspiration?Visit the

Create conversations programmatically


Active creation lets you populate conversations through the Conversation Orchestrator API or TwiML.

For a comparison with passive ingestion and guidance on which mode to use, see Ingestion modes.


Prerequisites

prerequisites page anchor

Create a conversation configuration

create-a-conversation-configuration page anchor

Send a POST request to the Configurations endpoint. Omit captureRules and use GROUP_BY_PROFILE so that conversations follow the same customer across channels and devices:

Create a conversation configuration for active creationLink to code sample: Create a conversation configuration for active creation
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 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
8
const accountSid = process.env.TWILIO_ACCOUNT_SID;
9
const apiKey = process.env.TWILIO_API_KEY;
10
const apiSecret = process.env.TWILIO_API_SECRET;
11
const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13
async function createConfiguration() {
14
const configuration = await client.conversations.v2.configurations.create({
15
displayName: "active-conversations",
16
description: "Configuration for API-created conversations",
17
conversationGroupingType: "GROUP_BY_PROFILE",
18
memoryStoreId: "YOUR_MEMORY_STORE_ID",
19
channelSettings: {
20
SMS: {
21
statusTimeouts: {
22
inactive: 30,
23
closed: 1440,
24
},
25
},
26
},
27
});
28
29
console.log(configuration.statusUrl);
30
}
31
32
createConfiguration();

Configuration creation is asynchronous. Poll the returned statusUrl until status is COMPLETED.


Create a conversation with participants

create-a-conversation-with-participants page anchor

Send a POST request to the Conversations endpoint with the participants you want to include. Always set the participant type explicitly so that profile resolution runs against the correct address.

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 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
8
const accountSid = process.env.TWILIO_ACCOUNT_SID;
9
const apiKey = process.env.TWILIO_API_KEY;
10
const apiSecret = process.env.TWILIO_API_SECRET;
11
const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13
async function createConversationWithConfig() {
14
const conversation = await client.conversations.v2.conversations.create({
15
configurationId: "YOUR_CONFIGURATION_ID",
16
name: "Support chat for Kiran",
17
participants: [
18
{
19
name: "Kiran A.",
20
type: "CUSTOMER",
21
addresses: [
22
{
23
channel: "SMS",
24
address: "+15551234567",
25
},
26
],
27
},
28
{
29
name: "Kai B.",
30
type: "HUMAN_AGENT",
31
addresses: [
32
{
33
channel: "SMS",
34
address: "YOUR_TWILIO_PHONE_NUMBER",
35
},
36
],
37
},
38
],
39
});
40
41
console.log(conversation.id);
42
}
43
44
createConversationWithConfig();

To add a participant after a conversation is created, send a POST request to the Participants endpoint on the conversation.


Optional: Ingest voice calls with TwiML

optional-ingest-voice-calls-with-twiml page anchor

For voice channels, you can use TwiML to ingest calls into conversations. Conversation Orchestrator adds the call (and its transcription) to the conversation you specify.

TwiML verbArchitectureUse case
<ConversationRelay>Synchronous bidirectional STT + TTS over WebSocket.AI voice agents.
<Transcription>Asynchronous fork of voice media for transcription.Human agent augmentation.

Route a call to a new conversation

route-a-call-to-a-new-conversation page anchor

Use <ConversationRelay> with conversationConfiguration to start a new conversation using the given configuration:

1
<Response>
2
<Connect>
3
<ConversationRelay
4
url="wss://your-voice-adapter/ws"
5
conversationConfiguration="YOUR_CONFIGURATION_ID" />
6
</Connect>
7
</Response>

Add transcription to an existing conversation

add-transcription-to-an-existing-conversation page anchor

Use <Transcription> with conversationId to add the call to a conversation you already created:

1
<Response>
2
<Start>
3
<Transcription conversationId="YOUR_CONVERSATION_ID" />
4
</Start>
5
<Say>Welcome to support. How can I help you today?</Say>
6
</Response>

Both <ConversationRelay> and <Transcription> accept conversationConfiguration and conversationId. If both are present, conversationId takes precedence and grouping rules are bypassed.

Parameters providedBehavior
conversationConfiguration onlyUses the configuration's grouping rules to find or create a conversation.
conversationId onlyRoutes directly to the specified conversation. Grouping rules are bypassed.
Both conversationConfiguration and conversationIdconversationId takes precedence. The configuration is ignored for routing.
NeitherNo Conversation Orchestrator integration. Transcription isn't captured.

Human handoff: Conversation Relay to Transcription

human-handoff-conversation-relay-to-transcription page anchor

When handing off from an AI agent to a human agent on the same call, end the Conversation Relay session and start <Transcription> with the same conversationId:

1
<Response>
2
<Start>
3
<Transcription conversationId="YOUR_CONVERSATION_ID" />
4
</Start>
5
<Dial>+15551234567</Dial>
6
</Response>

Both the AI portion and the human portion live in one conversation.

(warning)

Don't combine capture rules with active TwiML for the same call

If your configuration has voice capture rules and you pass conversationConfiguration on a <ConversationRelay> verb for the same call, you pay for STT twice. Remove voice capture rules from your configuration when using active TwiML with Conversation Relay. See the Voice channel documentation.