Interaction Logs from the Analytics API

The Analytics API is a new version of our ReportingAPI, with download facilities available through the CMS. The logs downloaded from the Analytics API will have the following columns:

Column Name	Description	Data type	nullable?	Notes
LogId	internal ID for each record	bigint	no
InteractionUuid	uuid for each separate interaction	uuid	no	See note on UUID
OriginatingInteractionUuid	for Feedback and Linkclicks, the uuid of the interaction the feedback/linkclick follows on from.	uuid	yes	See note on UUID
SessionUuid	uuid for each separate session	uuid	no	See note on UUID
SessionIsActive	true if any interaction in the session is of a maininteractiontype other than Event or DataRetrieval, or contains only the start of a Dialog and not any other Dialog interaction, otherwise false	boolean	no
TimestampStart	timestamp of the interaction when it entered the Platform, in UTC format	timestamp with time zone	no
TimestampEnd	timestamp of the interaction when it left the Platform, in UTC format	timestamp with time zone	no
Culture	Either the shorter language code, or the full culture code, as applicable for the interaction	text	no
MainInteractionType	The most relevant interactiontype from a recognition perspective -- a user asking a question will have QA here, even if the question is answered using a Dialog	text	no	See Note Maininteractiontype and allinteractiontypes
AllInteractionTypes	All the interactiontypes that were involved in the interaction. A user question that starts a Dialog will have [ "Dialog", "QA"] here	text(json)	no	See Note Maininteractiontype and allinteractiontypes
InteractionValue	A specific value. Depending on the interactiontype, this can be various things but it commonly is the user question or clicked dialog option	text	yes
OutputText	the Answer text returned to the user for this Interaction	text	yes
OutputMetadata	the additional meta-data of the Output, as logged in JSON or a JSON array. Usually an array of key/value pairs.	text (json)	yes
Channel	Information about the Channel for the Answer. {"name": Default, "type":"Text"}	text (json)	no
Contexts	The contexts we logged for this interaction. "id" and "name" should not be empty, "value" can be an empty string. JSON structure: [{"id": ,"name":"" ,"value":"" }]	text (json)	yes
ArticleIds	the articles used to provide an answer to this interaction. ["dn-1-1", "qa-1"]	text (json)	yes
DialogPaths	A json overview of which dialogpaths applied during the interaction. Started: the location in a dialog that was just started EndedOrInProgress: the location in an ongoing dialog or one that was ended to start a new one DropOut: should only appear for interactions not (only) of type Dialog: The location within a Dialog that this interaction dropped out of.	text (json)	yes	See note Dialogpaths
TDialogStatus	A JSON object consisting of all the nodes in the Tdialog with the names as keys and whether they are completed (filled with valid data) or not. Completed nodes will have a 1 as the value with the key, Open ones wil have a 0. JSON structure: [{"name":"", "status":""}]	text (json)	yes
FeedbackInfo	All the information relating to a feedback interaction: originatinginteractionuuid, label, score, comment.	text (json)	yes
LinkclickInfo	All the information relating to a linkclick interaction: originatinginteractionuuid, url	text (json)	yes
RecognitionType	What kind of recognition was used for Q&A interactions	text	yes
RecognitionQuality	Only _truly_ relevant for Q&A interactions of recognitiontype 'Entity Recognition'; a measure of how well the question in the CMS that was used to match the user question actually matched that user question, calculated at interaction time. In the dashboarding, the overall recognition quality is calculated using the Q&A interactions with recognitiontypes 'Entity Recognition', 'No Recognition' (quality is always 0) and 'Exception Event' (quality should always be 100)	numeric	yes
RecognitionDetails	JSON object containing all information about recognition, most notably:matched intent, matched entities, missing words. This can be present for Dialog interactions but will then only contain information about matched entities. JSON Structure: {"intentInfo": "", "isException": , "missingWords": "", "entityMatches": [], "missingArticle": "", "inputTextEntities": "", "recognitionQuality": }	text (json)	yes
GenerativeAISources	JSON object containing sources used in generating any AI generated answer and if present, the reasoning given for the answer. JSON structure: {"sources": [{"source": "", "content": "", "distance": }], "reasoning": ""}	text (json)	yes
Translation	If we translated the userinput in order to recognise it, this will say either 'Culture Selected' or 'Culture Detected'. If we did a detection but did not translate, it will say 'No Translation'. If we didn't even attempt a detection, this will be null.	text	yes
TranslationDetails	All the information we used when translating userinput, including the original input, what language we translated from, whether we determined that language via detection, and the confidence of the detection. If a translation has taken place, the 'originalinput' from this field is what the user actually typed in. JSON structure: {"confidence": , "detectionUsed": , "originalInput": "", "translationLanguage": ""}	text (json)	yes
Articles	JSON object containing all the information about the articles involved in answering the user question. JSON Structure: {"qa": [{"articleId": , "categories": [{"id": , "name": "", "parent": , "sortIndex": , "classification": {"id": , "name": ""}}]}], "dialog": [{"nodeId": , "dialogId": , "nodeName": "", "nodeType": "", "categories": [{"id": , "name": "", "parent": , "sortIndex": , "classification": {"id": , "name": ""}}], "dialogName": "", "dialogStatus": ""}]}	text (json)	yes	See note articles
Onlinecategory	The category (ies) the articles involved in the response are assigned to for the classification that was included in the request. JSON Structure: [{"id": , "name": "", "parent": , "sortIndex": , "classification": {"id": , "name": ""}}]	text (json)	yes
FaqsFound	For an FAQSearch or Dataretrieval interaction, the list of FAQs found.	text (json)	yes
Pages	A json object containing the originatingpage and the previouspage for the interaction. Not nullable but the page information may be an empty string	text (json)	no
CustomerProjectIdentifier	an identifier for the project, using CUSTOMERKEY_PROJECTKEY	text	no
PublishInfo	Information about when the knowledgebase that this interaction happened against was published and where.	text (json)	no
SessionDetails	Standard information about the session at the time the interaction took place. This includes ‘sessionisactive’ but unlike the separate column this one is not updated when the session becomes active	text (json)	no
AdditionalSessionInfo	Additional information about the session. For the moment his includes the useruuid and any userinfo marked as 'showinReporting'.	text (json)	yes
Variables	(Currently) always-empty field anticipating future use.	text(json)	yes

Notes:

UUID
A UUID is a Universal Unique Identifier. Conversational AI Cloud logging uses it to make sure that each Interaction and User and Session has a unique ID

MainInteractionType and AllInteractionTypes
In the old logs, we logged multiple rows with an identical interactionuuid. All these rows belonged to the same interaction. In the new AnalyticsAPI, all these rows are condensed into a single row. Allinteractiontypes are the (distinct) interactiontypes that would have been spread across the multiple rows in the ReportingAPI. Maininteractiontype is the interactiontype we consider the most important for the recognition of the user interaction, and it is also the column we use for grouping in for instance the Management Report/Monthly Report to show the counts of interactions per type.

If you want to retrieve all interactions of a given type, you should use AllInteractionTypes for filtering. For high-level overviews, the MainInteractionType is a better grouping value. Grouping or filtering on MainInteractionType will not show Dialog starts as Dialogs (unless they were started from another Dialog) and no Events that haven’t been directly activated.

We determine the MainInteractiontype based on the endpoint from our gateway (reference: https://developers.cm.com/conversational-ai-cloud/reference/get_ask ) and what is already active in the session:
A question coming in via the /ask endpoint and no T-Dialog, Dialog or HALO session is active: QA
A question coming in via the /ask endpoint with a tdialogstate parameter: Transactional Dialog

A question coming in via the /ask endpoint and we’re in a HALO session: GenerativeAI
A question coming in via the /ask endpoint with a Dialog active (either active in the session or with a dialogpath parameter), answered within that Dialog: Dialog

A question coming in via the /ask endpoint with a Dialog active (either active in the session or with a dialogpath parameter) but _not_ answered within that Dialog: QA

Coming in via the /dialogstep endpoint: Dialog
Coming in via the /feedback endpoint : Feedback

Coming in via the /linkclick endpoint : LinkClick

Coming in via the /event endpoint: Event -- Events activated through QA or Dialogs don’t get called via this endpoint, so have QA (or Dialog) as their MainInteractionType.

Coming in via the /faqs/id/output endpoint: FAQClick

Coming in via the /faqs endpoint with a searchText parameter: FAQSearch

Coming in via the /faqs endpoint(s) without a searchText parameter: DataRetrieval

Coming in via the /classifications endpoint(s): DataRetrieval

The other interactiontypes that are shown in AllInteractionTypes then play a role in providing the answer or gathering additional information; the Dialog started from the QA, FAQ, Event or other Dialog, the Event called because it was needed to answer the question, a GenerativeAI answer instead of a found QA article, and the DataRetrieval to provide related FAQs.

Dialogpaths

This field gives not just the information about which current node in the dialog an answer is coming from or that is calling a different article, but also records the path taken through the dialog to get to this stage, including non-interactive nodes that would otherwise not show up in these logs.

The format of the Dialogpath is: <dialogid>:<nodeid>/<nodeid>!
Everything after <dialogid>:<nodeid> is optional. The / separates nodes and the presence of ! indicates that the Dialog it reached an output node and could not continue any further, ending the Dialog. The first or only node in the path indicates from which node in the Dialog the dialog was entered, and each subsequent node one that was visited to ultimately reach the final node in the path.

Three different paths are possible on any given Dialog or QA interaction:
EndedOrInProgress
The final node on this path is providing the answer in the OutputText field or activated another Dialog.
Started
This Dialog started on this interaction.
DropOut
This Dialog was active in the session at the start of this interaction, but was not used to recognise the user’s input. Therefore, the user dropped out of this Dialog. You can use this to analyse where and why people drop out of Dialogs.