Skip to contentSkip to navigationSkip to topbar
Page tools
Useful for sharing or LLM
Accelerate development with AI

On this page
Looking for more inspiration?Visit the

Sync Conversation Insights data with Data Destinations


(new)

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.

Join the Data Destinations private beta

Get early access to native destinations for data warehouses, observability tools, and event pipelines.

Sign up(link takes you to an external page)

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 APIData Destinations
What you getAggregated results, such as last week's resolution rate.Individual conversation records.
Where you analyzeIn Twilio, through the API.In your destination's own tools.
Time rangeUp to 31 days per request.As long as you retain the records.
Best forOn-demand answers about your conversations.Reporting that combines conversations with your business data.

How it works

how-it-works page anchor
  1. A conversation closes in Conversation Orchestrator.
  2. Conversation Insights builds the ConversationSummary record and publishes it as a com.twilio.insights.conversation.summarized event.
  3. Data Destinations delivers the event to each destination with a subscription to that event type.
  4. 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.

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.

(information)

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.



Set up a destination in the Console

set-up-a-destination-in-the-console page anchor
  1. Sign in to Twilio Console(link takes you to an external page).

  2. In the left navigation, go to Data > Data Destinations > Destinations.

  3. 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.

  4. Under Select existing destination, select your destination. If you haven't set up a connection to it yet, click Add new destination.

  5. Select a destination that supports Conversation Insights. The list also includes destination types that don't support it.

  6. 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.

  7. The wizard returns you to Add destination subscription. Under Create Subscription, click Get started.

  8. 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.


Set up a destination with the API

set-up-a-destination-with-the-api page anchor

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}.

Create a destination

create-a-destination page anchor

Replace the uppercase placeholder values with your own Snowflake account identifier, database, schema, and key-pair credentials.

Create a Snowflake destination

create-a-snowflake-destination page anchor
1
curl -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.

Subscribe to ConversationSummary records

subscribe-to-conversationsummary-records page anchor
1
curl -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": 1
11
}
12
]
13
}'

The ConversationSummary record

the-conversationsummary-record page anchor

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 TaskCompletion becomes task_completion, and lists are arrays rather than comma-separated strings.
  • One object for custom measures. Instead of <Name><Aggregation> measures, the record has a single custom_measures object. See Custom measures.

The second column shows the ConversationSummary cube field that each record field comes from.

FieldConversationSummary fieldTypeDescription
conversation_idConversationIdstringThe unique identifier for the conversation. Use it to join with your other data.
conversation_nameConversationNamestringThe name of the conversation. Can contain personal data.
conversation_statusConversationStatusstringThe final status of the conversation.
channelsChannelsarray of stringsThe communication channels used in the conversation, such as VOICE and SMS.
date_createdCreatedDatestringWhen the conversation was created, in ISO 8601 format and UTC.
date_closedClosedDatestringWhen the conversation was closed, in ISO 8601 format and UTC.
intelligence_configuration_idsIntelligenceConfigurationIdsarray of stringsThe intelligence configurations associated with the conversation.
participant_countParticipants measuresintegerThe number of participants in the conversation. The cube aggregates this value with ParticipantsSum, ParticipantsAvg, ParticipantsMin, and ParticipantsMax.
has_human_agentHasHumanAgentbooleanWhether at least one human agent took part in the conversation.
has_ai_agentHasAIAgentbooleanWhether at least one AI agent took part in the conversation.
customer_profile_idCustomerProfileIdstringThe profile identifier for the customer participant. Left out of the record when the conversation has no customer profile.
custom_measures<Name><Aggregation> measuresobjectYour custom measures from Conversation Intelligence custom operators, keyed by the name you registered. See Custom measures.
Sentiment operator
sentimentSentimentstringThe 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_completionTaskCompletionstringThe 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_countHallucinationCountintegerThe 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_hallucinationHasHallucinationbooleanWhether 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_conflictHasExternalContextConflictbooleanWhether the agent contradicted your Enterprise Knowledge, Conversation Memory, or both. null when the operator didn't run on the conversation.
has_conversation_context_conflictHasConversationContextConflictbooleanWhether the agent contradicted something said earlier in the conversation. null when the operator didn't run on the conversation.
has_context_gapHasContextGapbooleanWhether 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 name you registered the measure with, such as LeadScore. It isn't the operator's output field, such as leadScore.
  • 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.

custom_measures with two registered measures

custom_measures-with-two-registered-measures page anchor
1
"custom_measures": {
2
"LeadScore": 82,
3
"QaScore": 4.5
4
}

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.

Example ConversationSummary record

example-conversationsummary-record page anchor
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": 82
17
},
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": false
25
}

Data Destinations delivers each record as the data object of a CloudEvent(link takes you to an external page):

ConversationSummary record in its event envelope

conversationsummary-record-in-its-event-envelope page anchor
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.


Calculate metrics that match Conversation Insights

calculate-metrics-that-match-conversation-insights page anchor

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.

MetricQuery APIRule
AI agent resolution rateConversationSummary.Count grouped by TaskCompletion, filtered on HasAIAgent EQ trueRESOLVED conversations divided by conversations with any task_completion label.
Resolution rate by agent typeConversationSummary.Count grouped by HasAIAgent, HasHumanAgent, and TaskCompletionThe resolution rate, calculated separately for each combination of agent flags.
AI agent hallucination rateConversationSummary.Count grouped by HasHallucination, filtered on HasAIAgent EQ truehas_hallucination true divided by conversations where has_hallucination isn't null.
Hallucination rate by typeConversationSummary.Count grouped by the three type dimensions, filtered on HasHallucination NE nullEach type flag that's true divided by conversations where has_hallucination isn't null.
Sentiment shareConversationSummary.Count grouped by SentimentConversations with each label divided by conversations where sentiment isn't null.
Custom measure averageConversationSummary.<Name>AvgThe 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 null in a Snowflake VARIANT column isn't a SQL NULL, so COUNT(payload:task_completion) includes conversations where the operator didn't run. Cast the field first, such as payload:task_completion::string.
  • Use date_created for time ranges. It's the same timestamp as ConversationSummary.CreatedDate, which the Query API examples filter on.

AI agent resolution rate

ai-agent-resolution-rate page anchor

The share of AI agent conversations where the agent resolved the customer's task.

1
SELECT
2
DATE_TRUNC('week', payload:date_created::timestamp) AS week,
3
COUNT_IF(payload:task_completion::string = 'RESOLVED')
4
/ NULLIF(COUNT(payload:task_completion::string), 0) AS resolution_rate
5
FROM TWILIO_EVENTS_<SUBSCRIPTION_ID>
6
WHERE event_type = 'com.twilio.insights.conversation.summarized'
7
AND payload:has_ai_agent::boolean
8
GROUP BY week
9
ORDER BY week;

Resolution rate by agent type

resolution-rate-by-agent-type page anchor

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.

Resolution rate by agent type

resolution-rate-by-agent-type-1 page anchor
1
SELECT
2
payload:has_ai_agent::boolean AS has_ai_agent,
3
payload:has_human_agent::boolean AS has_human_agent,
4
COUNT_IF(payload:task_completion::string = 'RESOLVED')
5
/ NULLIF(COUNT(payload:task_completion::string), 0) AS resolution_rate
6
FROM TWILIO_EVENTS_<SUBSCRIPTION_ID>
7
WHERE event_type = 'com.twilio.insights.conversation.summarized'
8
GROUP BY has_ai_agent, has_human_agent;

AI agent hallucination rate

ai-agent-hallucination-rate page anchor

The share of AI agent conversations with at least one hallucination. A context gap isn't counted as a hallucination.

1
SELECT
2
DATE_TRUNC('week', payload:date_created::timestamp) AS week,
3
COUNT_IF(payload:has_hallucination::boolean)
4
/ NULLIF(COUNT(payload:has_hallucination::boolean), 0) AS hallucination_rate
5
FROM TWILIO_EVENTS_<SUBSCRIPTION_ID>
6
WHERE event_type = 'com.twilio.insights.conversation.summarized'
7
AND payload:has_ai_agent::boolean
8
GROUP BY week
9
ORDER BY week;

Hallucination rate by type

hallucination-rate-by-type page anchor

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.

1
SELECT
2
DATE_TRUNC('week', payload:date_created::timestamp) AS week,
3
COUNT_IF(payload:has_external_context_conflict::boolean)
4
/ COUNT(*) AS external_context_conflict_rate,
5
COUNT_IF(payload:has_conversation_context_conflict::boolean)
6
/ COUNT(*) AS conversation_context_conflict_rate,
7
COUNT_IF(payload:has_context_gap::boolean)
8
/ COUNT(*) AS context_gap_rate
9
FROM TWILIO_EVENTS_<SUBSCRIPTION_ID>
10
WHERE event_type = 'com.twilio.insights.conversation.summarized'
11
AND payload:has_ai_agent::boolean
12
AND payload:has_hallucination::boolean IS NOT NULL
13
GROUP BY week
14
ORDER BY week;

The share of conversations with each sentiment label.

1
SELECT
2
DATE_TRUNC('week', payload:date_created::timestamp) AS week,
3
payload:sentiment::string AS sentiment,
4
COUNT(*) / SUM(COUNT(*)) OVER (PARTITION BY week) AS share
5
FROM TWILIO_EVENTS_<SUBSCRIPTION_ID>
6
WHERE event_type = 'com.twilio.insights.conversation.summarized'
7
AND payload:sentiment::string IS NOT NULL
8
GROUP BY week, sentiment
9
ORDER BY week, sentiment;

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.

1
SELECT
2
DATE_TRUNC('week', payload:date_created::timestamp) AS week,
3
AVG(payload:custom_measures:"LeadScore"::float) AS lead_score_avg
4
FROM TWILIO_EVENTS_<SUBSCRIPTION_ID>
5
WHERE event_type = 'com.twilio.insights.conversation.summarized'
6
GROUP BY week
7
ORDER BY week;

Data Destinations is free to use during the private beta. Pricing will be announced when Data Destinations reaches general availability.