Message Report endpoint

This endpoint allows you to extract message reports that include all the data collected for each of the messages produced/received by a bot during a certain period.

The endpoint may be hit using two different methods: GET (foreground execution) and POST (background execution for bigger data sets sent by email).

The REST API uses the following path: https://app.certainly.io/api/

We'll explore both methods noted above:

• Retrieve a Message Report (GET)
• Get a Message Report via email (POST)

Retrieve a Message Report (GET)

This request is synchronous and returns a list of messages in JSON format.

Please note that the maximum time range supported is 15 days, and the maximum number of data entries returned is 500. If you need to export a longer time interval or bigger data set, please refer to the asynchronous POST alternative below.

The endpoint that is attached under the domain is as follows:

This section includes:

• Example request cURL (GET)
• Headers (GET)
• Query parameters (GET)
• Example response (GET)

Example request cURL (GET)

Headers (GET)

Query parameters (GET)

Example response (GET)

Here, you can find definitions of the values included in the example response above:

• id: This value allows you to specify the row in the data where the user or a bot has taken a certain action.
• timestamp: Here you can observe the date and time of the conversation.
• message: Here you can see the user's input to the bot. It will show both which buttons the user has pressed (displayed as "Suggested Replies") and freely written text.
• response: This shows you the bot's answer to a user reply, but in a processed way. That means if you've used variations or the name of the user in the bot's reply Module, the data will be presented the same way as it's presented to the user.
  • text: This is the message that is sent in each speech bubble within a bot Module.
  • type: This indicates the type of expected response for each message. "Text" means the bot awaits a written response to continue the flow. "Wait" means a delay has been programmed between bot messages. "Choice" means the user has been provided with Suggested Replies to select from.
  • wait: This is the amount of programmed delay time between bot messages.
• conversation_id: This represents the ID of an entire conversation. This allows you to focus on a particular conversation flow in the bot, and you can see how many Modules have appeared in a conversation.
• through_bot_modules: This shows from which previous Modules the message was reached (useful for debugging).
• bot_module_id: This identifies the specific Module to which input has been made. If you are unsure where to find the Module number, please refer to "How to edit a Module" for an illustration.
• is_test: This indicates whether the conversation was live via the widget ("false"), or if it was from the tester mode in the bot-building canvas ("true").
• external_agent: This value is an ID assigned by a third-party integration to an agent.
• through_connection_id: This shows through which Connection the message was reached (useful for debugging).
• is_global_module_match: Here you will be able to see if a response was prompted by Global Connections. This provides insight into how the user is guided through the chatbot.
• is_deleted: This boolean is used to flag a logic deletion.
• id_message_evaluate: This is the ID of the specific Connection being matched for that Module.
• data: All the information regarding the Connections of a specific Module.
  • type: This indicates whether the Connection is local or global.
  • fallback: Here you can see if this Connection is a regular Connection with a condition attached ("false") or if it has no condition for its activation, making it a Fallback Connection ("true").
  • position: This indicates the order in which the Connections for this Module are being fired.
• user_message_empty: This indicates whether a message has been received from the user ("false") or has not ("true").
• bot_response_empty: Here you can see if the bot provided a message to the user in this Module ("false") or if it was an empty Module only firing/setting a Webhook, Connection, or variable, with the user going through unaware ("true").
• bot_module: Information regarding the specific Module to which input has been made. 
  • id: This is the Module ID for the Module to which input has been made.
  • name: Here you can see the name given to this Module.
  • type: Here you can see what type of Module it is (statement, multiple choice, etc.).
  • instruction: This allows you to see the Module message that will be displayed to the user, which can be useful if you want to compare it with a user reply. This also contains pre-processed responses, so if you have used variations or included a user's name, then this will appear the same way that it does in the editor mode.
  • error_instruction: This allows you to see the bot error message that will be displayed to the user when the user's input does not meet the set requirements. This is helpful for checking how often and when any errors occur.
  • is_global: This indicates whether the Connection that brought the bot to this Module was local or global.
  • priority: This indicates the internal priority index.
  • is_starting: Here you can see if the message belongs to the conversation's Starting Module ("true") or not ("false).
  • fallback_module_id: This indicates the Module ID of the designated Fallback for this Module.
  • skip_user_input: Here you can see if the "Don't wait for the user's input, just evaluate the Connections" checkbox for this Module is marked ("true") or unmarked ("false").
  • skip_global_connection_evaluation: Here you can see if the "Skip Global Connection" checkbox for this Module is marked ("true") or unmarked ("false").
  • group: If you have used the Groups tool, you can see data pertaining to the different paths.
  • kpis: Here you will see any KPI tags that have been added to a Module, allowing you to quickly find when and where a particular KPI tag was triggered.
    • label: The KPI tag label assigned to this Module.
    • colour: This indicates the KPI color grouping of this Module in the canvas.
    • id: This indicates the KPI color grouping ID of this Module in the canvas.
• botuser: Information regarding the user conversing with the bot.
  • id: This is the ID we give to your bot users, which can be useful if you need to identify a user.
  • created_date: The date when the bot user was created, which is when the user first opened a chat with this bot.
  • botuser_meta: Here you can see metadata related to the bot user.
    • web: Contains metadata collected automatically by the bot (only available in some channels).
      • host: This refers to the host part section of the URL on which the bot is deployed.
      • current_ip: This is the IP address of the website on which the bot is deployed.
      • hostPageUrl: This is the full URL of the website on which the bot is deployed.

Get a Message Report via email (POST)

This request is asynchronous, and it triggers the sending of a data set to the email account linked to the authentication token used. It allows the export of data for time intervals of more than 15 days and total number of entries greater than 500.

The report is attached to the email as a CSV file. To view the data correctly, you will need to import the CSV file into Excel.

The endpoint path is as follows:

This section includes:

• Example request cURL (POST)
• Headers (POST)
• Body (POST)
• Example response (POST)

Example request cURL (POST)

Headers (POST)

The header parameters for this request must also include your JWT user token and the content/type specification. For a more in-depth explanation of how to use them, refer to the previous information on headers.

Body (POST)

The query parameters are the same as in the GET request, which can be seen above.

Example response (POST)

If the request is valid and accepted, the following response is returned:

If another previous request was requested, the following response is returned: