Human API for Export

Export API v3

Export API v3 allows you to search for conversations and export their contents in a machine-readable format. The available search filters are the same as can be found in the "conversations" page in Admin Panel.

Changelog

Changes in v12.3.3.5

• Conversation.quality_label is taken from the last session
• Conversation.reviewed is true whenever any session has been reviewed

Changes in v11.4.0

• New Question and Answer field session_id.
• Marks question in Question as being optional, which may happen on very old conversations
• Added support for OAuth 2.0 tokens

Changes in v11.3.0

• New MessageContent type ssml for speech markup.
• New ButtonClicked element, which is a Button with the extra field source_url.

Changes in v11.2.5

• Intent field title is now optional.

Changes in v11.2.4

• Corrected schema key names in UserInformation and Log.source.

Changes in v11.1.0

• New Button field attributes.
• New Conversation field user_information.
• New SentenceAnalysis fields intent and winner.

Changes in v11.0.4

• New Answer field human_agent.
• New Conversation field authentication_identifier.

Changes in v11.0.3

• Answer field filterrenamed to matched_filter.
• Question field filtersrenamed to sent_filter_values.
• New Answer field sent_filter_values.

Overview

The API endpoint is located at

https://<yoursite>.boost.ai/api/export/v3

and accepts POST requests with the following headers:

Content-Type: application/json

Authorization: Bearer <bearer_token>

Note: All passwords or other authentication information to and from external systems used in APIs, such as this bearer token, must be handled as sensitive information and shared in a secure manner during configuration.

In addition to the bearer token, the client IP address must be added to the allowlist in Admin Panel under Settings, Security and Privacy, IP and domain allowlist.

Furthermore, we strongly recomment adding the following headers:

Accept-Encoding: deflate, gzip

This will allow the server to compress the output, which may save up to 95% of the bytes sent, making the download much faster.

The response will be a chunked stream consisting of JSON. See below for the format.

On errors, you will receive a non-200 HTTP status code and an error message. If the error happens before the export stream has started up, it will be a single JSON object:

{ "type": "error", "message": "description here" }

If an error happens during export, it will be part of a list of output objects:

[ ..., { "type": "error", "message": "description here" } ]

Authorization (Bearer token)

As of v11.4, this endpoint now supports access tokens issued from the OAuth 2.0 token endpoint. In order for the token to be accepted the scope "export:v3" is required.

Additionally, a client can be restricted to only be able to export conversations meeting certain criteria using by setting the token payload (see the OAuth 2.0 documentation for how to do this):

• If only_masked is set to true, the client is only able to export anonymized conversations
• If sent_filter_values is set to ["filter1", "filter2"], the client is only allowed to export conversations where these filter values were passed.
• If environment is set to either "live" or "staging", the client can only export conversations in the respective environment.

Example

Below is a simple request sent to the export API. The from and to keys are required, and in this case match any conversation taking place in 2021. However, we also specify that we want a particular conversation by providing the conversation ID 1000001.

{ "from": "2021-01-01", "to": "2022-01-01", "conversation_ids": [1000001] }

The response body we get is very detailed. Since we are only exporting one conversation, and no errors have occurred, it has the following general structure:

[ <QueryInfo>, <Conversation>, <PostQueryInfo> ]

The QueryInfo object contains information about the interpreted query along with the number of matching conversations found:

{ "type": "query_info", "interpreted_query_range": [ "2021-01-01T00:00:00+01:00", "2022-01-01T00:00:00+01:00", ], "current_time": "2021-01-28T17:38:09.512966+01:00", "query_seconds": 0.0008645057678222656, "query": { "conversation_ids": [1000001], "environment": "live", "from": "2021-01-01", "only_masked": false, "to": "2022-01-01", }, "conversations": 1, }

The PostQueryInfo object is used for debugging, and provides us with statistics:

{ "type": "post_query_info", "query_seconds": 0.015825357791115234, "total_seconds": 0.86910080909729, "serialization_seconds": 0.8691000938415527, "secs/conversation": 0.8691000938415527, "conversations/sec": 1.1582535779166046, "conversations": 1, }

A Conversation object gives high-resolution information about a single conversation. This specific example is a short conversation where:

• The VA welcomes the user.
• The user writes "Show me all content".
• The VA responds with text, buttons, a picture and a video.
• The user clicks a button.

Example:

{ "type": "conversation", "id": 1000001, "reference": "b7a86e480bc54edc573cad0b4226e4c8", "environment": "live", "time": { "created": "2021-01-28T17:20:48.812727+01:00", "last_message_created": "2021-01-28T17:20:59.324965+01:00", }, "reviewed": false, "messages": [ { "id": 1000003, "time": "2021-01-28T17:20:48.833936+01:00", "is_human_chat": false, "type": "answer", "actions": { "displayed": { "type": "action", "action_type": "content", "id": 3002, "language": "en-US", "transfer_to_human": false, } }, "system_action_trigger": "welcome_action", "content": [ { "type": "text", "text": "<p>Hi!</p>", "time": "2021-01-28T17:20:48.837365+01:00", }, { "type": "text", "text": "<p>What can I help you with?</p>", "time": "2021-01-28T17:20:48.841254+01:00", }, ], }, { "id": 1000004, "time": "2021-01-28T17:20:52.170427+01:00", "is_human_chat": false, "type": "question", "question": { "type": "question_analysis", "input": "Show me all content.", "predicted_language": "en-US", "sentiment": "neutral", "labels": ["Perfect Match"], "analysis": [ { "processed": "show myself everyth content", "translated": "show myself everyth content", "winner": true, "intent": { "type": "intent", "id": 1014, "title": "All content", "inherit_skill": true, }, } ], "important_words": ["content", "everyth"], }, "source_url": "<source URL>", "device": "desktop", "intents": { "predicted": { "type": "intent", "id": 1014, "title": "All content", "inherit_skill": true, } }, }, { "id": 1000005, "time": "2021-01-28T17:20:52.186811+01:00", "is_human_chat": false, "type": "answer", "actions": { "displayed": { "type": "action", "action_type": "content", "id": 3064, "language": "en-US", "transfer_to_human": false, } }, "intents": { "came_from": { "type": "intent", "id": 1014, "title": "All content", "inherit_skill": true, } }, "content": [ { "type": "text", "text": "<p>Here's all kinds of content:</p>", "time": "2021-01-28T17:20:52.188995+01:00", }, { "type": "image", "url": "<image URL>", "time": "2021-01-28T17:20:52.192158+01:00", }, { "type": "video", "url": "<video URL>", "time": "2021-01-28T17:20:52.197405+01:00", "video_fullscreen": false, "video_type": "vimeo", }, { "type": "json", "time": "2021-01-28T17:20:52.201831+01:00", "json": {"some": "json"}, }, { "type": "link", "time": "2021-01-28T17:20:52.205736+01:00", "buttons": [ { "type": "button", "id": 7, "button_type": "action", "text": "Action buttons", }, { "type": "button", "id": 8, "button_type": "url", "text": "Boost.AI", "url": "https://www.frankenthalerfoundation.org", }, { "type": "button", "id": 9, "button_type": "action", "hidden": true, "text": "Hidden button", }, { "type": "button", "id": 10, "button_type": "action", "text": "Api arrays", }, { "type": "button", "id": 11, "button_type": "action", "text": "Named api arrays", }, { "type": "button", "id": 12, "button_type": "action", "text": "JSON", }, ], }, ], }, { "id": 1000006, "time": "2021-01-28T17:20:59.324965+01:00", "is_human_chat": false, "type": "answer", "button_clicked": { "type": "button", "id": 7, "button_type": "action", "hidden": false, "text": "Action buttons", }, "actions": { "came_from": { "type": "action", "action_type": "content", "id": 3064, "language": "en-US", "transfer_to_human": false, }, "displayed": { "type": "action", "action_type": "content", "id": 3065, "language": "en-US", "transfer_to_human": false, }, }, "intents": { "came_from": { "type": "intent", "id": 1014, "title": "All content", "inherit_skill": true, } }, "content": [ { "type": "text", "text": "<p>Action button reply</p>", "time": "2021-01-28T17:20:59.330268+01:00", }, { "type": "link", "time": "2021-01-28T17:20:59.333326+01:00", "buttons": [ { "type": "button", "id": 13, "button_type": "action", "text": "More buttons", } ], }, ], }, ], }

Endpoints

POST /v3/ (Exports conversations)

Request

Request body

Content-Type: application/json A client request specifying what to export.

There are only two required keys, from and to. They specify the search range, which is the basis for all the other filters.

For a conversation to be exported, it must have had some kind of end-user interaction in the search range.