Core concepts

Conversation Orchestrator organizes your voice calls, SMS messages, and WhatsApp messages into conversations. You can observe traffic in your Twilio account and add communications to conversations using capture rules, or group communications into conversations directly using TwiML or the API.

Conversation Orchestrator uses a memory store to identify customers and keep information about them. When you add Conversation Intelligence, Twilio can analyze those conversations.

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. You can create as many conversation configurations as you need, and each conversation belongs to exactly one conversation configuration.

Create separate conversation configurations when your use cases have different requirements for channel mix, timers, memory store, or intelligence configurations. For example, a sales use case might allow customers to reply over several days before a conversation closes, while a high-throughput customer care use case might close conversations after 10 minutes of inactivity.

A configuration includes:

• The grouping type. See Conversation grouping.
• A link to a memory store.
• Per-channel settings, including capture rules (passive ingestion only) and timeouts.
• Optional intelligence configurations.
• Optional status callbacks.

The conversationGroupingType on your configuration controls how new traffic groups into conversations.

Kiran contacts you four times:

1. SMS from +15551234567 to your number.
2. Voice call from +15551234567 to your number.
3. WhatsApp from +15551234567 to your number.
4. SMS from +15559876543 (their other phone) to your number.

All four interactions pass the configuration's capture rules. The conversationGroupingType then decides how they land in conversations.

Update your conversation configuration by making a PUT request to the Configuration resource. Send the complete configuration object with every update. Any parameter that you omit from the PUT request body is deleted from the conversation configuration.

Configuration updates only apply to newly created conversations. Existing active conversations continue using the configuration that was in effect when they were created. To apply new settings to an active conversation, close it and let a new one be created.

The one exception is statusCallbacks. You can modify statusCallbacks on an active conversation configuration, and the change takes effect immediately.

Each account supports up to 10 conversation configurations and up to 100 capture rules per channel per configuration. For details, see Configuration limits.

A conversation is a record of interactions between participants. It's the container for all communications that occur during an interaction, including voice calls, SMS messages, and other supported channels.

Conversations move through three states: ACTIVE, INACTIVE, and CLOSED. See Conversation lifecycle for state transitions and timeouts.

A communication is the smallest unit of interaction within a conversation. Each communication represents a single event, such as an SMS message or a voice call transcription.

For messaging channels, the communication's content contains the message body. For voice channels, it contains the speech-to-text transcript. Each communication also includes an author, recipients with delivery status, a resourceId linking to the original Twilio resource (Message SID or Call SID), and timestamps.

A participant represents an actor involved in a conversation. Conversation Orchestrator assigns each participant a type that identifies their role.

Only participants with type CUSTOMER get profiles. For how types are determined and how resolution runs, see Profiles.

A profile is a customer identity record stored in a memory store. Profiles let Conversation Orchestrator recognize returning customers across conversations, link multiple addresses (phone or chat) to one identity, and drive profile-based grouping.

Conversation Orchestrator matches each CUSTOMER participant to a profile using the participant's channel address. When a communication shares an address with an existing profile (for example, an SMS message and a voice call from the same E.164 number), Conversation Orchestrator links them to the same profile.

• Profiles: How participant types are identified and profiles are resolved.
• Ingestion modes: Passive, active, and classic-bridge modes.
• Conversation lifecycle: State transitions and timeouts.
• Channels: Channel-specific behavior.
• Quickstart: Create your first conversation configuration.