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 click, rate 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:
-
Check if the answer has
parameters.trackingCode.rateCodeset (For more information, see "Answer attributes and parameters" in API Answer types)-
Use
rateCodeto evaluate the quality of the content and track it in the logs. You can add a comment to the rating if needed.
-
Use
-
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.