Sync Conversation Insights data with Data Destinations
Beta
Data Destinations is currently available as a Private Beta product and the information contained in this document is subject to change. Data Destinations is not a HIPAA Eligible Service or PCI compliant and should not be enabled in workflows that are subject to HIPAA or PCI. To learn more, see Private beta legal information.
Get early access to native destinations for data warehouses, observability tools, and event pipelines.
Conversations are most valuable when you can analyze them alongside the rest of your business. Use Data Destinations to sync Conversation Insights data to the data warehouses, BI, and product analytics tools your team already uses, such as Snowflake, BigQuery, or Amplitude. Join it with your proprietary data, such as CRM accounts, orders, or product usage, and build the reports and dashboards you need on top of it, without building or maintaining a custom ETL pipeline.
When a conversation closes, Conversation Insights sends a single record that summarizes it. The record includes:
- Conversation details, such as channels, timestamps, and participants.
- Operator results, such as sentiment, AI agent task completion, and hallucination detection.
- Your custom measures.
Each conversation is one flat record, so you can query it, report on it, and visualize it without joining tables or reshaping data first.
Data Destinations sends individual records, not aggregated results. You aggregate and query them in your destination, and the Conversation Insights Query API doesn't read data from your destination.
| Conversation Insights Query API | Data Destinations | |
|---|---|---|
| What you get | Aggregated results, such as last week's resolution rate. | Individual conversation records. |
| Where you analyze | In Twilio, through the API. | In your destination's own tools. |
| Time range | Up to 31 days per request. | As long as you retain the records. |
| Best for | On-demand answers about your conversations. | Reporting that combines conversations with your business data. |
- A conversation closes in Conversation Orchestrator.
- Conversation Insights builds the ConversationSummary record and publishes it as a
com.twilio.insights.conversation.summarizedevent. - Data Destinations delivers the event to each destination with a subscription to that event type.
- You aggregate and query the records in your destination.
The com.twilio.insights.conversation.summarized event type is available in the United States (US1) region only.
| Category | Destinations |
|---|---|
| Warehouses | Snowflake, BigQuery, Databricks |
| Observability | Datadog, Splunk, Grafana Cloud, New Relic |
| Product analytics | Amplitude, Google Analytics 4, Mixpanel |
| Raw data streaming | Webhook, Amazon Kinesis, Apache Kafka, Google Cloud Pub/Sub, Azure Event Hubs |
| Other | Airtable, Slack |
Product analytics destinations track events per user, so Data Destinations uses the record's customer_profile_id as the user identifier. This is a Conversation Memory profile ID, so it doesn't match user IDs you already send to these tools unless you map them.
Info
Slack and Airtable accept low request volumes. Every closed conversation produces one event, so use a warehouse or streaming destination for production-scale volume. To learn more, see the Destination comparison.
-
Your account is enrolled in the Data Destinations (private beta).
-
You're an Account Owner or Account Administrator, or you have a Data Destinations role. Account Owners and Account Administrators have access by default. Other users need one of these roles:
- Destinations Admin to create and manage destinations and subscriptions.
- Destinations Viewer to only view destinations and subscriptions.
To assign a role, in the Twilio Console, go to Settings > Organization settings > Users, click the user, click Role Assignments, and add the role. To learn more, see RBAC in Twilio Console.
-
Conversation Intelligence is set up with rules that run the operators you want to export. Fields for operators that don't run on a conversation are
null. -
To include custom measures, register them.
-
Sign in to Twilio Console.
-
In the left navigation, go to Data > Data Destinations > Destinations.
-
Click Add destination subscription to open the setup wizard.
(information)Info
If Add destination subscription is unavailable and shows Destinations Admin permission required, your user doesn't have the Destinations Admin role yet. Assign the role, then reload the page.
-
Under Select existing destination, select your destination. If you haven't set up a connection to it yet, click Add new destination.
-
Select a destination that supports Conversation Insights. The list also includes destination types that don't support it.
-
Enter the credentials and configuration for your destination type, then save the destination. For destination-specific settings, see the page for your destination in Data Destinations.
-
The wizard returns you to Add destination subscription. Under Create Subscription, click Get started.
-
Enter a name for your subscription. Expand Conversation Insights, select the Conversation Insights Summarized event (
com.twilio.insights.conversation.summarized), and keep Use latest schema version turned on. Then click Save subscription.
Your destination now receives a ConversationSummary record each time a conversation closes.
To manage destinations programmatically instead of in the Console, use the Destinations API. Create a destination, then create a subscription to the com.twilio.insights.conversation.summarized event type. For a full walkthrough, including authentication, catalog lookups, and asynchronous operations, see the Destinations API quickstart.
The following example creates a Snowflake destination for illustration, to match the SQL in Calculate metrics that match Conversation Insights. Create whichever destination type you want from the supported destinations, and get its config shape from the destination type catalog with GET https://destinations.twilio.com/v1/Catalog/DestinationTypes/{destinationType}.
Replace the uppercase placeholder values with your own Snowflake account identifier, database, schema, and key-pair credentials.
1curl -X POST "https://destinations.twilio.com/v1/ControlPlane/Destinations" \2-u $TWILIO_API_KEY:$TWILIO_API_SECRET \3-H "Content-Type: application/json" \4-d '{5"destinationType": "snowflake",6"name": "Conversation summaries",7"config": {8"account": "ACCOUNT",9"database": "DATABASE",10"schema": "SCHEMA",11"credentials": {12"credentialType": "KEY_PAIR",13"username": "USERNAME",14"privateKey": "PRIVATE_KEY"15}16}17}'
The response includes the destination id, such as tde_dest_01k88r5c5fg21bzmsxpaz3d9r0.
1curl -X POST "https://destinations.twilio.com/v1/ControlPlane/Subscriptions" \2-u $TWILIO_API_KEY:$TWILIO_API_SECRET \3-H "Content-Type: application/json" \4-d '{5"description": "Conversation Insights summaries",6"destinationId": "tde_dest_01k88r5c5fg21bzmsxpaz3d9r0",7"eventTypes": [8{9"eventType": "com.twilio.insights.conversation.summarized",10"schemaVersion": 111}12]13}'
Each com.twilio.insights.conversation.summarized event carries one ConversationSummary record for a single conversation. The record is a variant of a ConversationSummary cube row, adapted for delivery to your systems, so it doesn't match the cube one to one:
- Per-conversation values only. The record holds the values for one conversation, not the cube's measures, such as counts and rates. You calculate those in your destination. See Calculate metrics that match Conversation Insights.
- Snake case names and arrays. Field names use snake case, so
TaskCompletionbecomestask_completion, and lists are arrays rather than comma-separated strings. - One object for custom measures. Instead of
<Name><Aggregation>measures, the record has a singlecustom_measuresobject. See Custom measures.
The second column shows the ConversationSummary cube field that each record field comes from.
| Field | ConversationSummary field | Type | Description |
|---|---|---|---|
conversation_id | ConversationId | string | The unique identifier for the conversation. Use it to join with your other data. |
conversation_name | ConversationName | string | The name of the conversation. Can contain personal data. |
conversation_status | ConversationStatus | string | The final status of the conversation. |
channels | Channels | array of strings | The communication channels used in the conversation, such as VOICE and SMS. |
date_created | CreatedDate | string | When the conversation was created, in ISO 8601 format and UTC. |
date_closed | ClosedDate | string | When the conversation was closed, in ISO 8601 format and UTC. |
intelligence_configuration_ids | IntelligenceConfigurationIds | array of strings | The intelligence configurations associated with the conversation. |
participant_count | Participants measures | integer | The number of participants in the conversation. The cube aggregates this value with ParticipantsSum, ParticipantsAvg, ParticipantsMin, and ParticipantsMax. |
has_human_agent | HasHumanAgent | boolean | Whether at least one human agent took part in the conversation. |
has_ai_agent | HasAIAgent | boolean | Whether at least one AI agent took part in the conversation. |
customer_profile_id | CustomerProfileId | string | The profile identifier for the customer participant. Left out of the record when the conversation has no customer profile. |
custom_measures | <Name><Aggregation> measures | object | Your custom measures from Conversation Intelligence custom operators, keyed by the name you registered. See Custom measures. |
| Sentiment operator | |||
sentiment | Sentiment | string | The latest label from the Sentiment operator: positive, negative, neutral, or mixed. null when the operator didn't run on the conversation. |
| Task Completion operator (public beta) | |||
task_completion | TaskCompletion | string | The latest label from the Task Completion operator: RESOLVED, UNRESOLVED, ESCALATED, or AGENT_DECLINED. null when the operator didn't run on the conversation. |
| Hallucination Detection operator (public beta) | |||
hallucination_count | HallucinationCount | integer | The number of hallucinations found, counting each distinct combination of conflict type and source once. A context gap isn't counted. null when the operator didn't run on the conversation. |
has_hallucination | HasHallucination | boolean | Whether the operator found at least one hallucination. A context gap isn't counted as a hallucination. null when the operator didn't run on the conversation. |
has_external_context_conflict | HasExternalContextConflict | boolean | Whether the agent contradicted your Enterprise Knowledge, Conversation Memory, or both. null when the operator didn't run on the conversation. |
has_conversation_context_conflict | HasConversationContextConflict | boolean | Whether the agent contradicted something said earlier in the conversation. null when the operator didn't run on the conversation. |
has_context_gap | HasContextGap | boolean | Whether the agent made a claim that can't be verified against your knowledge, memory, or the conversation. null when the operator didn't run on the conversation. |
To learn how each value is calculated, see ConversationSummary dimensions. Label values are case-sensitive: sentiment labels are lowercase, and task completion labels are uppercase. New fields can be added to the record over time, so build your integration to ignore fields it doesn't recognize.
The custom_measures field holds the values of every custom measure you've registered from a Conversation Intelligence custom operator. It's an object with one key per measure:
- Key: The
nameyou registered the measure with, such asLeadScore. It isn't the operator's output field, such asleadScore. - Value: The number the operator produced for this conversation. If the operator ran more than once on the conversation, the record has the latest result.
1"custom_measures": {2"LeadScore": 82,3"QaScore": 4.54}
A measure is left out of the object when its operator didn't run on the conversation, so don't treat a missing key as zero. The object is empty when you haven't registered any measures. Registration applies going forward only, so a measure appears only in records for operator runs after you registered it.
1{2"conversation_id": "conv_conversation_01ks4d7f1jffrrhfdmxrgk3epa",3"conversation_name": "Order status inquiry",4"conversation_status": "CLOSED",5"channels": ["VOICE", "SMS"],6"date_created": "2026-10-21T16:00:00.000Z",7"date_closed": "2026-10-21T16:12:30.000Z",8"intelligence_configuration_ids": [9"intelligence_configuration_01knmybwv2eecb1n6gyche3dee"10],11"participant_count": 2,12"has_human_agent": false,13"has_ai_agent": true,14"customer_profile_id": "mem_profile_xbvx6n988v7nnqc11e1bnneh0c",15"custom_measures": {16"LeadScore": 8217},18"sentiment": "positive",19"task_completion": "RESOLVED",20"hallucination_count": 1,21"has_hallucination": true,22"has_external_context_conflict": true,23"has_conversation_context_conflict": false,24"has_context_gap": false25}
Data Destinations delivers each record as the data object of a CloudEvent:
1{2"specversion": "1.0",3"type": "com.twilio.insights.conversation.summarized",4"id": "databridge_event_fa7b1a8a593643d59995fc987a7aac82",5"time": "2026-10-21T16:13:45.000Z",6"datacontenttype": "application/json",7"dataschema": "https://events-schemas.twilio.com/Insights.ConversationSummary/1",8"data": {9"conversation_id": "conv_conversation_01ks4d7f1jffrrhfdmxrgk3epa",10"conversation_status": "CLOSED",11"task_completion": "RESOLVED"12}13}
The data object in this example is shortened. How the envelope arrives depends on the destination: webhook destinations receive an array of CloudEvents, and warehouse destinations store the event in a payload column. See the page for your destination for its format.
After records arrive in your destination, you calculate metrics yourself. To get the same numbers as the Conversation Insights Query API, use the same rule for each metric. Most importantly, leave out conversations where the operator didn't run. Those fields are null, and counting them lowers your rates.
| Metric | Query API | Rule |
|---|---|---|
| AI agent resolution rate | ConversationSummary.Count grouped by TaskCompletion, filtered on HasAIAgent EQ true | RESOLVED conversations divided by conversations with any task_completion label. |
| Resolution rate by agent type | ConversationSummary.Count grouped by HasAIAgent, HasHumanAgent, and TaskCompletion | The resolution rate, calculated separately for each combination of agent flags. |
| AI agent hallucination rate | ConversationSummary.Count grouped by HasHallucination, filtered on HasAIAgent EQ true | has_hallucination true divided by conversations where has_hallucination isn't null. |
| Hallucination rate by type | ConversationSummary.Count grouped by the three type dimensions, filtered on HasHallucination NE null | Each type flag that's true divided by conversations where has_hallucination isn't null. |
| Sentiment share | ConversationSummary.Count grouped by Sentiment | Conversations with each label divided by conversations where sentiment isn't null. |
| Custom measure average | ConversationSummary.<Name>Avg | The average of the measure across conversations that have a value. |
The following examples use Snowflake and group results by week. A Snowflake destination writes events to a table named TWILIO_EVENTS_<SUBSCRIPTION_ID>, with the record in the payload column. For other destinations, apply the same rules in that tool's query language. When you write your own queries, keep these points in mind:
- Cast fields before you count them. A JSON
nullin a SnowflakeVARIANTcolumn isn't a SQLNULL, soCOUNT(payload:task_completion)includes conversations where the operator didn't run. Cast the field first, such aspayload:task_completion::string. - Use
date_createdfor time ranges. It's the same timestamp asConversationSummary.CreatedDate, which the Query API examples filter on.
The share of AI agent conversations where the agent resolved the customer's task.
1SELECT2DATE_TRUNC('week', payload:date_created::timestamp) AS week,3COUNT_IF(payload:task_completion::string = 'RESOLVED')4/ NULLIF(COUNT(payload:task_completion::string), 0) AS resolution_rate5FROM TWILIO_EVENTS_<SUBSCRIPTION_ID>6WHERE event_type = 'com.twilio.insights.conversation.summarized'7AND payload:has_ai_agent::boolean8GROUP BY week9ORDER BY week;
The resolution rate for conversations handled only by an AI agent, only by a human agent, or by both. A conversation that an AI agent hands off to a human agent has both flags set to true.
1SELECT2payload:has_ai_agent::boolean AS has_ai_agent,3payload:has_human_agent::boolean AS has_human_agent,4COUNT_IF(payload:task_completion::string = 'RESOLVED')5/ NULLIF(COUNT(payload:task_completion::string), 0) AS resolution_rate6FROM TWILIO_EVENTS_<SUBSCRIPTION_ID>7WHERE event_type = 'com.twilio.insights.conversation.summarized'8GROUP BY has_ai_agent, has_human_agent;
The share of AI agent conversations with at least one hallucination. A context gap isn't counted as a hallucination.
1SELECT2DATE_TRUNC('week', payload:date_created::timestamp) AS week,3COUNT_IF(payload:has_hallucination::boolean)4/ NULLIF(COUNT(payload:has_hallucination::boolean), 0) AS hallucination_rate5FROM TWILIO_EVENTS_<SUBSCRIPTION_ID>6WHERE event_type = 'com.twilio.insights.conversation.summarized'7AND payload:has_ai_agent::boolean8GROUP BY week9ORDER BY week;
The share of analyzed AI agent conversations with each finding type. A conversation can have more than one type, so it can count toward more than one rate.
1SELECT2DATE_TRUNC('week', payload:date_created::timestamp) AS week,3COUNT_IF(payload:has_external_context_conflict::boolean)4/ COUNT(*) AS external_context_conflict_rate,5COUNT_IF(payload:has_conversation_context_conflict::boolean)6/ COUNT(*) AS conversation_context_conflict_rate,7COUNT_IF(payload:has_context_gap::boolean)8/ COUNT(*) AS context_gap_rate9FROM TWILIO_EVENTS_<SUBSCRIPTION_ID>10WHERE event_type = 'com.twilio.insights.conversation.summarized'11AND payload:has_ai_agent::boolean12AND payload:has_hallucination::boolean IS NOT NULL13GROUP BY week14ORDER BY week;
The average value of a custom measure. Replace LeadScore with the name you registered the measure with. Snowflake path names are case-sensitive, so match the name exactly.
1SELECT2DATE_TRUNC('week', payload:date_created::timestamp) AS week,3AVG(payload:custom_measures:"LeadScore"::float) AS lead_score_avg4FROM TWILIO_EVENTS_<SUBSCRIPTION_ID>5WHERE event_type = 'com.twilio.insights.conversation.summarized'6GROUP BY week7ORDER BY week;
Data Destinations is free to use during the private beta. Pricing will be announced when Data Destinations reaches general availability.
- Core concepts: Learn what each ConversationSummary field means and how it's calculated.
- Supervise AI agents: Set up the Task Completion and Hallucination Detection operators.
- Define and use custom fields: Add your own measures to the summary.
- Destinations overview: Learn more about Data Destinations.