Developers

API Tracking Guidelines

Default Chatbot Tracking Actions

What is tracked and how? 

By default, Chatbot API event tracking is extensive. Each event is associated with an atomic log, a session log or both, which determines where the information will be available in the application Dashboard. 

Events listed according to a log type are shown in atomic logs. Events listed according to data keys are shown in Sessions logs. Events with both can be shown in both places. This table shows all log types and data keys that come predefined in a Chatbot instance.

Log type
(Atomic)
Data key
(Session)
Action
- START Marks the start of the session.
- USER_BROWSER Stores the browser information of the user.
- USER_INFO Stores the user information in session.
- CHATBOT_INTENT_ABORT Indicates that a dialog was ended prematurely, without the Chatbot reaching the final response.
- CHATBOT_INTENT_END_FAILED Indicates that the Chatbot was unable to return the final response for an ongoing dialog.
- CHATBOT_INTENT_END_RESPONDED Indicates that the Chatbot returned the final response for an ongoing dialog.
- CHATBOT_INTENT_START Indicates that the Chatbot has started a dialog intent.
- CONTACT_START Indicates a user started filling a contact form, converting the session in a contact session.
- CONTACT_SUBMIT Indicates a user clicked submit on a contact form. (This does not mean the form was submitted.)
- CONTACT_TICKET Indicates a user created a ticket and is being forwarded to another channel.
- MY_CUSTOM_KEY Custom data key to track customer events.
SEARCH SEARCH Indicates the user performed a search.
SEARCH SEARCH_EXTERNAL_CMS Indicates that a user search resulted in contents from an external Content Management System (non-Inbenta contents).
MATCH CLICK_MATCH Indicates a user clicked on a result.
CONTENT CLICK_CONTENT Indicates a user reached a page that contains a content, e.g. through a link.
RELATED CLICK_RELATED Indicates a user clicked on a related content.
CHAINED CLICK_CHAINED Indicates a user clicked on content within a decision tree.
RATING RATE_CONTENT Indicates a user submitted a rating evaluating a specific content.
CHAINED AUTOMATIC_CHAINED_TRANSITION Indicates that Chatbot transitioned automatically to a node of a dialog.
- VARIABLES Indicates that a variable was captured.
- VARIABLES_ERROR Indicates that an explicit variable capture (i.e. directly set using POST conversation/variables or webhooks) failed.
CONTENT DIRECT_CALL Indicates that a direct call was requested.
- DIRECT_CALL_ERROR Indicates that a direct call was requested but the direct call does not exist.
CONTENT DIRECT_ANSWER Indicates that a Chatbot preset answer was returned (if Direct Answer is mapped as Content).
- NL_CHAINED_TRANSITION Indicates that a user moved to the next node of a chained dialog using natural language search.
- NL_MULTIPLE Indicates that a user selected one of multiple results using natural language search.
- NL_CHAINED_NO_MATCH Indicates that a user tried to select the next node using natural language search but there was no match with the available nodes.
- NL_MULTIPLE_NO_MATCH Indicates that a user tried to select one of multiple results using natural language search, but there was no match with the available results.
- WEBHOOK Indicates that Chatbot launched a webhook.
- ACTION_DATA_FIELD Indicates that a data field of an action was presented to the user.
- ACTION_ABORT Indicates that a user cancelled an action.
- ACTION_RETRY Indicates that a user selected to retry a failed action.
- ERROR Indicates that an error happened in the chatbot.
- CONTACT_ATTENDED Indicates that a user accepted the escalation offer from the Chatbot and there were agents available to get the chat.
- CONTACT_UNATTENDED Indicates that a user asked for escalation but there were no agents available. 
- CONTACT_REJECTED Indicates that Chatbot offered escalation but the user rejected it.
MATCH CLICK_EXTERNAL_BASE Indicates a click in a result from a external base (Chatbot Search or KM API).
MATCH CLICK_EXTERNAL_CMS Indicates a click in a result from an external Content Management System (non-Inbenta result).
MATCH CLICK_AIML Indicates that an AIML result was returned.
- CONVERSATION_START_SETTINGS Indicates the conversation settings values for a series of parameters including skipLastCheckQuestion, maxOptions, maxRelatedContents, allowUserToAbandonForm, errorRetries, and folderFiltering.
- CHAINED_BUTTONS Indicates that the Chatbot offered one or more dialog nodes with the button transition type.
- CHAINED_ONE_BY_ONE_START Indicates the initial intro text of the dialog when the transition type is one by one.
- CHAINED_ONE_BY_ONE_POLAR_ANSWER Indicates that, after the Chatbot offered a dialog node using a Yes/No question, the user responded with either Yes or No.
- CHAINED_ONE_BY_ONE_OPTION Indicates the Chatbot offered one or more dialog nodes using a series of Yes/No questions.
- CHAINED_NLS Indicates the Chatbot asked an open question in order to transition via natural language to one or more dialog nodes.
- CHAINED_BUTTONS_CLICK Indicates the Chatbot did not offer one or more dialog nodes because they were unavailable at the moment (e.g. publication expired date).
- CHAINED_IGNORED_CHILDREN Indicates that a transition from one dialog node to another has occurred.
- DIALOG_TRANSITION Indicates the user clicked on a dialog node offered via the button transition type.
- MULTIPLE_BUTTONS_CLICK Indicates the user clicked on a multiple option link.
- MULTIPLE_BUTTONS Indicates that the Chatbot offered more than one result as a series of clickable links.
- MULTIPLE_ONE_BY_ONE_OPTION Indicates that the Chatbot offered more than one result as using a series of Yes/No Check questions.
- MULTIPLE_ONE_BY_ONE_POLAR_ANSWER Indicates that, after the Chatbot offered more than one result as using a series of Yes/No Check questions, the user responded with either Yes or No.
LANGUAGE_DETECTION LANGUAGE_DETECTION Indicates that a language detection search was performed.
- CALLBACK Indicates that the Chatbot launched a callback.
- ACTION_DATA_FIELD_DATE Indicates a data field of type Date was asked to the user.
- ACTION_DATA_FIELD_ERROR Indicates a user introduced a wrong value on answering a data field
- ACTION_DATA_FIELD_LIST Indicates a data field of type list was asked to the user
- ACTION_DATA_FIELD_START Indicates that the first field of an action was asked to the user
- DYNAMIC_REDIRECT Indicates that a dynamic redirect is performed
- DYNAMIC_REDIRECT_ERROR Indicates that a dynamic redirect failed
- EXTERNAL_RESULTS Indicates that a set of external results was returned by Chatbot
- NO_RESULTS Indicates that the engine has not found any result for the last user question
- RATING Indicates that a rating was introduced by the user
- WEBHOOK_ERROR Indicates that a webhook responded with a controller error
- WEBHOOK_UNEXPECTED_ERROR Indicates that a webhook responded with an unexpected error (timeout, webhook not found, etc)
- INTENT_START Indicates that a user began an intent.
- INTENT_ABORT Indicates that a user ended the intent early without reaching the final response.
- INTENT_END_RESPONDED Indicates that the Chatbot returned a final response to the intent.
- INTENT_END_FAILED Indicates that the Chatbot was unable to return a final response to the intent.
- CHAT_ATTENDED Indicates that a user accepted the escalation offer from the Chatbot and that there were agents available to get the chat.
- CHAT_ESCALATION_REJECTED Indicates that a user rejected the escalation offer from the Chatbot.
- CHAT_NO_AGENTS Indicates that a user accepted the escalation offer from the Chatbot but there were no available agents to get the chat.
- CHAT_UNATTENDED Indicates that a user accepted the escalation offer from the Chatbot, and there were available agents, but none of them got the chat.

Data keys

A data key also has a priority level that is given to its event. The session reports use the priority of an event to decide the most important event performed by the user. This most important event becomes the result of the session.

Example: The user enters input that triggers the bot to offer chat with a human but then the user rejects the escalation offer. After some further interactions with the Chatbot, the user requests to chat with a human and an agent is available who attends the chat. The result of the session will be "Escalated > Accepted > Available Agents > Chat Attended", because the data key "CHAT_ATTENDED" has a higher priority (1) than the "CHAT_ESCALATION_REJECTED" data key (2).

Priority Data Key
1 (highest) CHAT_ATTENDED
CONTACT_TICKET (deprecated)
CONTACT_ATTENDED (deprecated)
2 CHAT_ESCALATION_REJECTED
CHAT_NO_AGENTS
CHAT_UNATTENDED
CONTACT_CLICK (deprecated)
CONTACT_SUBMIT (deprecated)
CONTACT_START (deprecated)
CONTACT (deprecated)
CONTACT_UNATTENDED (deprecated)
CONTACT_REJECTED (deprecated)
3 CLICK_MATCH
6 CLICK_CONTENT
7 CLICK_RELATED
CLICK_CHAINED
CLICK_EXTERNAL_BASE
CLICK_EXTERNAL_CMS
8 CLICK_AIML
EXTERNAL_RESULTS
MULTIPLE_BUTTONS
MULTIPLE_ONE_BY_ONE_OPTION
9 SEARCH
SEARCH_EXTERNAL_CMS
10 (lowest) START
0 (no priority) USER_INFO
USER_BROWSER
RATE_SEARCH
AUTOMATIC_CHAINED_TRANSITION
VARIABLES
VARIABLES_ERROR
DIALOG_TRANSITION
DIRECT_CALL
DIRECT_CALL_ERROR
DIRECT_ANSWER
NL_CHAINED_TRANSITION
NL_MULTIPLE
NL_CHAINED_NO_MATCH
NL_MULTIPLE_NO_MATCH
WEBHOOK
ACTION_DATA_FIELD
ACTION_ABORT
ACTION_RETRY
ERROR
LANGUAGE_DETECTION
CALLBACK
ACTION_DATA_FIELD_DATE
ACTION_DATA_FIELD_ERROR
ACTION_DATA_FIELD_LIST
ACTION_DATA_FIELD_START
CHAINED_BUTTONS
CHAINED_BUTTONS_CLICK
CHAINED_IGNORED_CHILDREN
CHAINED_NLS
CHAINED_ONE_BY_ONE_OPTION
CHAINED_ONE_BY_ONE_POLAR_ANSWER
CHAINED_ONE_BY_ONE_START
CHATBOT_INTENT_ABORT
CHATBOT_INTENT_END_FAILED
CHATBOT_INTENT_END_RESPONDED
CHATBOT_INTENT_START
CONVERSATION_START_SETTINGS
DYNAMIC_REDIRECT
DYNAMIC_REDIRECT_ERROR
MULTIPLE_BUTTONS_CLICK
MULTIPLE_ONE_BY_ONE_POLAR_ANSWER
NO_RESULTS
RATING
WEBHOOK_ERROR
WEBHOOK_UNEXPECTED_ERROR
INTENT_START
INTENT_ABORT
INTENT_END_RESPONDED
INTENT_END_FAILED

Optional Chatbot Tracking Actions

It is up to the botmaster to decide whether or not to track additional data.

All default tracking done by the API is described in detail above and in API Routes. In addition, Inbenta provides tracking codes for every content shown. You can use these codes to call the API and create logs, and track user data such as clicks and ratings. For accurate bot usage analysis, Inbenta strongly recommends that you track as many event types as possible, such as clickrate and custom events. 

You can find how to set up event trackers in the "tracking/events" section of the API routes.

Recommended tracking for Federated Bot logs (extendedContentsAnswer)

When Federated Bot is enabled, we consider the Chatbot instance as the primary instance, and the connected instance (Knowledge or Search) as the external one. In this case, Inbenta recommends that you log the data as follows:

Chatbot instance must contain all the tracking information of the implementation. This means:

  • Any user question performed
  • Any result returned by both Knowledge Bases (the Chatbot Knowledge Base and the external instance’s Knowledge Base)
  • Any click on the contents from both Knowledge Bases (the Chatbot Knowledge Base and the external instance’s Knowledge Base)
    • The clicks on the contents from the external instance will appear as “External” in the logs, to differentiate them from the Chatbot Knowledge Base intents.

External instance must contain:

  • Any user question performed (both in the Chatbot solution and the external solution)
  • Any result returned by the external instance’s Knowledge Base 

Rate

When a user rates a content, you should call the API with a rate event and log the RATE in the non-session log. The logged data includes the content ID, the rate code and the comment if added (optional).

Displaying ratings

To display ratings options for a given answer, check the following:

  1. Check if the answer has parameters.trackingCode.rateCode set (For more information, see "Answer attributes and parameters" in API Answer types)
    • Use rateCode to evaluate the quality of the content and track it in the logs. You can add a comment to the rating if needed.
  2. Check if the answer has the "no-ratings" flag set.
    • When the "no-ratings" flag is set, Inbenta recommends that you do not show ratings for this answer.

Recommended tracking for escalation to an external provider

The Inbenta-provided NL-Escalation-Adapter-2 handles escalation to Inbenta HyperChat and tracking of that escalation in all sessions dashboards. For more information about how you can track the agent conversation when you build custom escalation to a non-Inbenta provider, see External Chat Tracking.

Custom

In addition to the default events listed above and API Routes, you can set up and track custom events as required by your specific needs.