Ultimate | How to use the API

How to use the API

Welcome to the gateway of seamless data liberation – the Data Export API. Our Data Export API serves as the key to unlocking the full potential of your bot, empowering you to export conversation data and integrate it across diverse platforms and applications. Whether you’re a developer, business analyst, or IT professional, our API provides a streamlined and secure solution to extract valuable insights and conversation metadata, enabling you to drive innovation, make informed decisions, and propel your organization to new heights.

This article introduces the usage and outputs of the Data Export API.

To use the API, reach out to your CSM.

Generate an API Token

Generating a Token can only be done by users with an admin role.

Navigate to User Management -> Organization Management
Open your Organization profile
Navigate to API Key on the left menu
Click on Generate and hit the save button
Copy the key and keep it safe

Once you exit the Organization management page, you won’t have access to the token. If you have lost the token you generated before, you can simply revoke it by clicking on the Regenerate button. The validity of the old token will be revoked and you can use the newly generated token.

File Schema

The output of the API is a JSON document with all the conversations for a given day, following the structure outlined here:

Property	Description	Type
bot_id	Bot’s unique ID	string
bot_name	Bot’s name	string
conversation_id	Ultimate generated conversation ID	string
platform_conversation_id	CRM-specific ID	string
conversation_start_time	Date and time of when the conversation started based on UTC timezone	string
conversation_end_time	Date and time of when the conversation ended based on UTC timezone	string
language	Language of the conversation	string
channel	Channel of the conversation. Either chat or ticket	string
labels	A list of all the labels associated with the conversation	string[]
conversations_data	The session parameters are associated with the conversations. It is a list of the parameter’s key where it had a value. The undefined keys won’t be in this list. Note: even though it is stored as a string, the “conversations_data” contains another JSON object Example: `"conversations_data": {` `"parameter1": true,` `"parameter2": "parameter_value",` `"parameter3": "1234"` `}`	string
test_mode	A flag to identify if the conversation is a test conversation	boolean
conversation_status	Resolution of the conversation. Example: `bot_handled`	string
last_resolution	This is the final resolution of the conversation. It could be informed, resolved, escalated, or undefined.	string
triggered_replies		string
triggered_intent_replies	The intent based replies.	string[]
is_llm_conversation	A flag to identify if the conversation is a LLM conversation (at least have one LLM answer)	boolean
llm_notUnderstood_count	The count of not-understood messages in the LLM conversation	string
llm_responseGenerated_count	The count of response-generated messages in the LLM conversation	string
llm_errorOccurred_count	The count of error occurred messages in the LLM conversation	string
llm_escalationRequired_count	The count of escalationRequired messages in the LLM conversation	string
llm_fallback_count	The count of fallback messages in the LLM conversation	string
bot_messages_count	The count of bot messages	string
visitor_messages_count	The count of visitor messages	string
not_understood_messages_count	The count of the not understood messages in general	string

Popular Metrics

Congratulations! You have successfully exported the bot’s conversation data. Here are some of our suggestions to start the data exploration journey of the exported files.

Ultimate Metrics

SELECT
--Total conversations
count(distinct conversation_id) total_conversations,

--Bot handled rate
count(distinct case when conversation_status = 'botHandled' then conversation_id end) bot_handled_conversations,
count(distinct case when conversation_status = 'botHandled' then conversation_id end)/count(distinct conversation_id) bot_handled_rate,

--Deflection rate
count(distinct case when conversation_status not in ('email', 'agent', 'customEscalation') then conversation_id end)/count(distinct conversation_id) deflection_rate,

--Escalation rate
count(distinct case when conversation_status in ('email', 'agent', 'customEscalation') then conversation_id end)/count(distinct conversation_id) escalation_rate,

--Failed escalation rate
count(distinct case when conversation_status = 'failedEscalation' then conversation_id end)/count(distinct conversation_id) failed_escalation_rate,

--Informed rate
count(distinct case when last_resolution = 'informed' then conversation_id end)/count(distinct conversation_id) informed_rate,

--Automation rate
count(distinct case when last_resolution in ('informed', 'resolved') then conversation_id end)/count(distinct conversation_id) automation_rate,

--Message understood rate
(sum(visitor_messages_count)-sum(not_understood_messages_count
))/sum(visitor_messages_count) messages_understood_rate

FROM TABLE

First / Last Intent from a conversation

select
distinct conversation_id,
triggered_intent_replies[safe_offset(0)].intent_name first_intent,
array_reverse(triggered_intent_replies)[safe_offset(0)].intent_name last_intent
FROM TABLE

Metrics by first meaningful (or filtered) intent

with meaningful_intents as (
select conversation_id, first_meaningful_intent, conversation_status from
(
select distinct conversation_id,
intent.intent_name first_meaningful_intent,
conversation_status,
--order by ascending intent_timestamp for last intent
ROW_NUMBER() OVER (PARTITION BY conversation_id order by intent.intent_timestamp asc) rn,
FROM TABLE
LEFT JOIN UNNEST(triggered_intent_replies) intent
--select only intents that are labeled as meaningful
where intent.not_meaningful is false
--filter for specific intents
and intent.intent_name not in ('Greeting', 'Talk to a human/agent')
)
where rn=1
)

--calculate metrics for each intent
select first_meaningful_intent,
count(distinct conversation_id) total_conversations,
count(distinct case when conversation_status = 'botHandled' then conversation_id end)/count(distinct conversation_id) bot_handled_rate
from meaningful_intents
group by first_meaningful_intent
order by total_conversations desc

FAQs

Are the exported files immutable or do they change over time, requiring you to re-sync them?

The exported files are immutable, so they do not have to be reimported, thus making your BI pipeline less error-prone

I see differences in conversation counts for a specific date between the exported conversations and Bot Summary analytics. what could be the reason?

The exported data for a specific date has data only for conversations that ended on that date. This is a different approach than in the bot summary analytics, where any conversation at any state is included. This is done for multiple reasons, among them are: export file immutability and duplicate data prevention

Then how can I achieve parity between the numbers reported in the bot summary and the exported files?

To get a complete picture of all conversations that took place on a certain day x, you can just ingest the file generated for day x and day x + 1. By ingesting files from these two dates, you ensure that you will have counted all the conversations for date x, even if it spilled over to the next day

I see differences in conversation counts for a specific date between the exported conversations and Conversation Logs. What could be the reason?

Remember that the exported data for a specific date has data only for conversations that ended on that date. This is a different approach than in the conversation logs, where any conversation at any state is included to enable real-time debugging

Does a conversation include information about all replies triggered in a conversation, even if those replies happened on a previous day?

Yes. If a conversation is included in the file, it will have all of its data, even if it occurred on a previous day.

My virtual agent has conversations as part of the suggestion engine, will those appear in the export?”

Yes. Although in the bot summary dashboard these are excluded, these will still be available in the exported data. To exclude these and achieve parity with bot summary dashboard, filter by “bot_messages_count > 0”