Conversation Reporting

Conversation Reporting API

The conversation reporting API enables open-ended queries of your conversation metrics so you can build extensible reporting applications around your team's Drift performance.

POST https://driftapi.com/reports/conversations

Generic body format:

{
  "filters": [
    {
      "property": string,
      "operation": string (see list of options below),
      "values": [object] (optional, see table below)
    }
  ],
  "metrics": [string] //list of property strings
}

{
  "filters":[
    {
      "property": "lastAgentId",
      "operation": "HAS_PROPERTY"
    },
    {
      "property": "firstCloseAt",
      "operation": "BETWEEN",
      "values": [
        "2019-07-22",
        "2019-07-26" //numeric millisecond timestamp may also be used
      ]
    }
  ],
  "metrics": [
    	"timeToCloseMillis",
    	"timeToAgentResponseMillis",
    	"firstAgentMessageAt",
    	"relatedPlaybookId"
  ]
}

In short, this particular request would request any conversation between two dates that an agent (not just a bot) participated in, and display how long the conversation was open for, how long it took the agent to respond once routed in, the timestamp of the first agent message during the conversation, and the related playbook ID (if applicable) the conversation started from. Note that "agent" is your app user (your sales rep, support agent, etc).

❗️
All metrics must be numeric.

{
    "count": 48,
    "data": [
        {
            "conversationId": 852054511,
            "metrics": [
                4941610,
                1208305,
                1563910480819,
                671581
            ]
        }, ...
     ]
}

The response body contains both the number of discovered conversations, as well as the data of the query. The interpretation of this response would be that 48 found conversations between 2019-07-22 and 2019-07-26 contained an agent chatting in, along with data on each conversation (only 1 of the 48 conversations shown above for brevity).

🚧
An important note on Reporting API rate limits
The reporting API is subject to stricter rate limits and is subject to a capped rate of 60 calls per minute.

Acceptable Property Values

Use one of the following per metric or filter:

🚧
If a metric is not present, will return as "NaN". Metrics must be numeric.

String properties below specified as filter only.

name	definition
relatedPlaybookId	ID of related playbook for the conversation
createdAt	Timestamp when the conversation was created (ms)
endUserId	ID of the end user (site visitor)
endUserInitiated	True/false - whether the end user started the conversation
endUserType (*filter only*)	Type of the end user {USER, END_USER, NONE, LEAD}
firstAgentId	ID of the first agent that responded to the conversation
lastAgentId	ID of the last agent that responded to the conversation
firstAgentMessageAt	Timestamp of the first agent response (ms)
firstBotId	ID of the first bot
firstBotMessageAt	Timestamp of the first bot message (ms)
firstCloseAt	Timestamp of when the conversation was first closed (ms)
firstEndUserMessageAt	Timestamp of the first end user message
id	ID of the conversation
numAgentMessages	Number of agent messages in the conversation
numBotMessages	Number of bot messages in the conversation
numEndUserMessages	Number of end user messages in the conversation
offline	Is the conversation currently offline
pageUrl (*filter only*)	Page url of the conversation
status (*filter only*)	Current status of the conversation, one of {open, closed, pending, archived}
tags	Tags on the conversation
timeToAgentResponseMillis	Time until the first agent response (ms)
timeToCloseMillis	How long the conversation took to close (ms)
updatedAt	Last time the conversation was updated (ms)
botStatus	Bot status in the conversation, one of { BOT_ONLY, HUMAN_ONLY, BOT_ASSISTED, NO_RESPONSE}
cqlScore	The current CQL score of the conversation. Values between [-1, 3] corresponding to the number of bolts. -1 means disqualified, 0 means unassigned.

These will be used in the body of the query described below.

Structuring the Query

The query is structured with 2 different properties.

Query

filters - a list of Filter objects. All filters are and'd together.
metrics - a list of properties that represent numeric values for a conversation

Filter

property - required the name of an object property.
operation - required a filter operation to be applied to the property
values - a value list to use for comparison (for plural operations such as BETWEEN).

The filters should help narrow down your query to your particular data subset of interest (e.g. all closed conversations between a particular date, or all conversations with an agent (not just bot only) like the sample above).

field	type	definition
property	string	Property (use one of the above property values)
operation	string	one of - `EQ` - document field exact matches `value` - `NOT_EQ` - document field does not exactly match `value` - `GT` - document field is greater than `value` - `GTE` - document field is greater than or equal to `value` - `LT` - document field is less than `value` - `LTE` - document field is less than or equal to `value` - `IN` - document field is one of `values` - `NOT_IN` - document field is not one of `values` - `BETWEEN` - document field is between the first two items within `values` - `HAS_PROPERTY` - document has the field specified by `property` - `NOT_HAS_PROPERTY` - document does not have the field specified by `property` - `CONTAINS` - document field contains the substring `value` - `NOT_CONTAINS` - document field does not contain the substring `value`
values	object list	A value list to use for comparison on plural operations.

Metrics

property - required the name of an object property to return per conversation

field	type	definition
property	string	Property (use one of the above property values)

📘
A Note on Query Errors
If you get a "check query formatting" error, it can also indicate that your query was accepted syntactically, but was rejected by the search engine. For example, this could occur when a metric property/type pair combination is not supported.

🚧
Make your Queries fast
The public conversations reporting API is powerful, but currently not designed for long running queries. In particular, queries will time out after 10 seconds. Please keep them concise.

Conversation Reporting