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

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 asking to chat with a human but then there are no agents available. After some further interactions with the Chatbot, the user again requests to chat with a human and this time there is an agent available. The result of the session will be "User Accepted", because the data key "CONTACT_ATTENDED" has a higher priority (1) than the "CONTACT_UNATTENDED" data key (2). 

Priority Data Key
1 (highest) CONTACT_TICKET
CONTACT_ATTENDED
2 CONTACT_CLICK
CONTACT_SUBMIT
CONTACT_START
CONTACT
CONTACT_UNATTENDED
CONTACT_REJECTED
3 CLICK_MATCH
6 CLICK_CONTENT
7 CLICK_RELATED
CLICK_CHAINED
CLICK_EXTERNAL_BASE
8 CLICK_AIML
9 SEARCH
10 (lowest) START
0 (no priority) USER_INFO
USER_BROWSER
RATE_SEARCH
AUTOMATIC_CHAINED_TRANSITION
VARIABLES
VARIABLES_ERROR
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

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 extendedContentsAnswer

When Federated Bot is enabled, if the search returns a Federated Bot match (from KM or Search), no click is tracked by default. Inbenta recommends that you log these CLICK in both non-session and session logs. There are several possibilities depending on the number of results and whether or not the results are clickable by the user:

Matches Data logged
single match CLICK + Content ID of matched content
multiple, user selects one CLICK + Content ID of matched content
multiple, non-clickable CLICK + Content ID of clicked content

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

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.