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 English, 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.

Updated 5 days ago

Conversation Reporting


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.