Conversations - Overall Report

The conversations report provides statistics about conversation volume over a given time range. You may optionally specify two time ranges to see how conversation volume changed between the two ranges.

Note: The reporting endpoints are only available to Plus and Pro plans.

Request

GET /v2/reports/conversations HTTP/1.1
Authorization: Bearer oauth_token

URL Parameters

Parameter Type Examples Description
start date start=2019-05-02T12:00:00Z
Start of the interval
end date end=2019-06-02T12:00:00Z
End of the interval
previousStart date previousStart=2019-04-02T12:00:00Z
Start of the previous interval
previousEnd date previousEnd=2019-05-02T12:00:00Z
End of the previous interval
mailboxes number mailboxes=123
mailboxes=123,567
List of comma separated ids to filter on mailboxes
tags number tags=99787
tags=5666,99787
List of comma separated ids to filter on tags
types enumeration types=email
List of comma separated conversation types to filter on, valid values are email, chat, phone
folders number folders=991
folders=991,992
List of comma separated folder ids to filter on folders

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "filterTags" : [ {
    "name" : "tag a",
    "id" : 2
  }, {
    "name" : "tag b",
    "id" : 3
  } ],
  "busiestDay" : {
    "day" : 3,
    "hour" : 0,
    "count" : 411
  },
  "busyTimeStart" : 11,
  "busyTimeEnd" : 13,
  "current" : {
    "startDate" : "2015-01-01T00:00:00Z",
    "endDate" : "2015-01-31T23:59:59Z",
    "totalConversations" : 1816,
    "conversationsCreated" : 1698,
    "newConversations" : 1698,
    "customers" : 1302,
    "conversationsPerDay" : 60
  },
  "previous" : {
    "startDate" : "2014-01-01T00:00:00Z",
    "endDate" : "2014-01-01T23:59:59Z",
    "totalConversations" : 2080,
    "conversationsCreated" : 1976,
    "newConversations" : 1976,
    "customers" : 1479,
    "conversationsPerDay" : 67
  },
  "deltas" : {
    "newConversations" : -14.068825910931,
    "totalConversations" : -12.692307692308,
    "customers" : -11.967545638945,
    "conversationsCreated" : -14.068825910931,
    "conversationsPerDay" : -10.44776119403
  },
  "tags" : {
    "count" : 351,
    "top" : [ {
      "id" : 1,
      "count" : 1465,
      "previousCount" : 1651,
      "percent" : 80.671806167401,
      "previousPercent" : 79.375,
      "deltaPercent" : 1.2968061674009
    }, {
      "name" : "tag a",
      "id" : 2,
      "count" : 51,
      "previousCount" : 63,
      "percent" : 2.8083700440529,
      "previousPercent" : 3.0288461538462,
      "deltaPercent" : -0.22047610979329
    }, {
      "name" : "tag b",
      "id" : 406031,
      "count" : 24,
      "previousCount" : 20,
      "percent" : 1.3215859030837,
      "previousPercent" : 0.96153846153846,
      "deltaPercent" : 0.36004744154524
    } ]
  },
  "customers" : {
    "count" : 1816,
    "top" : [ {
      "count" : 31,
      "deltaPercent" : 0.31281768891901,
      "id" : 1,
      "name" : "John Smith",
      "percent" : 1.7070484581498,
      "previousCount" : 29,
      "previousPercent" : 1.3942307692308
    }, {
      "count" : 12,
      "deltaPercent" : -0.10843781768892,
      "id" : 2,
      "name" : "Mary Jones",
      "percent" : 0.66079295154185,
      "previousCount" : 16,
      "previousPercent" : 0.76923076923077
    } ]
  },
  "replies" : {
    "count" : 109,
    "top" : [ {
      "name" : "Saved Reply 1",
      "id" : 1,
      "mailboxId" : 1,
      "count" : 16,
      "previousCount" : 9,
      "percent" : 0.88105726872247,
      "previousPercent" : 0.43269230769231,
      "deltaPercent" : 0.44836496103016
    }, {
      "name" : "Saved Reply 2",
      "id" : 2,
      "mailboxId" : 1,
      "count" : 13,
      "previousCount" : 12,
      "percent" : 0.715859030837,
      "previousPercent" : 0.57692307692308,
      "deltaPercent" : 0.13893595391393
    } ]
  },
  "workflows" : {
    "count" : 240,
    "top" : [ {
      "name" : "Workflow 1",
      "id" : 1,
      "count" : 90,
      "previousCount" : 82,
      "percent" : 4.9559471365639,
      "previousPercent" : 3.9423076923077,
      "deltaPercent" : 1.0136394442562
    }, {
      "name" : "Workflow 2",
      "id" : 2,
      "count" : 75,
      "previousCount" : 91,
      "percent" : 4.1299559471366,
      "previousPercent" : 4.375,
      "deltaPercent" : -0.24504405286344
    } ]
  },
  "customFields" : {
    "count" : 1,
    "fields" : [ {
      "id" : 8,
      "name" : "Account Type",
      "mailboxId" : 1234,
      "values" : [ {
        "name" : "Paying Customer",
        "id" : 7,
        "count" : 1442,
        "percent" : 55.12232415902141
      }, {
        "name" : "Trial Customer",
        "id" : 11,
        "count" : 273,
        "percent" : 10.435779816513762
      } ],
      "summary" : {
        "total" : 2616,
        "totalAnswered" : 2241,
        "previousTotal" : null,
        "previousTotalAnswered" : null,
        "unansweredDelta" : 14.3348623853211,
        "unansweredPreviousPercent" : 0,
        "unansweredPercent" : 14.3348623853211
      }
    } ]
  }
}

Response fields

Path Type Description
filterTags Array All tags available for filtering in reports, including tag id=1, which represents conversations that are untagged
busiestDay Object Contains the busiest day and hour, along with the number of conversations associated with that day/time; days are indexed starting with Monday=1, Tuesday=2, etc., and hours from 0-23.
busyTimeStart Number Starting hour of the busiest time range, in the company’s time zone
busyTimeEnd Number Ending hour of the busiest time range, in the company’s time zone
current Object Statistics about conversation volume for the current time range
previous Object Statistics about conversation volume for the previous time range; only included if a previous time range was specified
deltas Object Statistics showing how conversation volume changed between two time ranges; only included if a previous time range was specified
tags Object Statistics about the most popular tags
customers Object Statistics about the most active customers
replies Object Statistics about the most frequently used saved replies
workflows Object Statistics about the most frequently used workflows
customFields Object Statistics about the most frequently used custom fields

Response fields

Path Type Description
startDate String Start of the range
endDate String End of the range
totalConversations Number Number of conversations handled during the time range
conversationsCreated Number Number of conversations created in this time range
newConversations Number Number of conversations created (by customers or Users) during the time range
customers Number Number of customers your company has replied
conversationsPerDay Number Average number of new or updated (a reply is sent to a customer) conversations

Response fields

Path Type Description
newConversations Number Percentage change in number of conversations created (by customers or Users) between time ranges
totalConversations Number Percentage change in number of total conversations between time ranges
customers Number Percentage change in number of customers between time ranges
conversationsCreated Number Percentage change in number of conversations created (by customers or Users) between time ranges
conversationsPerDay Number Percentage change in number of conversations per day between time ranges

Response fields

Path Type Description
count Number Number of tags used for the current time range
top Array Top tags used in the current time range, sorted from most to least used
top[].id Number This tag’s unique identifier
top[].name String This tag’s name
top[].count Number Number of times this tag was used in the current time range
top[].previousCount Number Number of times this tag was used the previous time range; only included if a previous time range was specified
top[].percent Number Percentage of total conversations in which this tag was used for the current time range
top[].previousPercent Number Percentage of total conversations in which this tag was used for the previous time range; only included if a previous time range was specified
top[].deltaPercent Number Change in percentage of total conversations in which this tag was used from the previous to current time ranges; only included if a previous time range was specified

Response fields

Path Type Description
count Number Total number of customer conversations for the current time range
top Array Top customers for the current time range, sorted from most to least active
top[].count Number Number of conversations for this customer in the current time range
top[].deltaPercent Number Change in percentage of total conversations belonging to this customer from the previous to current time ranges; only included if a previous time range was specified
top[].id Number This customer’s unique identifier
top[].name String This customer’s full name
top[].percent Number Percentage of total conversations belonging to this customer for the current time range
top[].previousCount Number Number of conversations for this customer for the previous time range; only included if a previous time range was specified
top[].previousPercent Number Percentage of total conversations belonging to this customer for the previous time range; only included if a previous time range was specified

Response fields

Path Type Description
count Number Number of saved replies sent for the current time range
top Array Top saved replies the current time range, sorted from most to least sent
top[].count Number Number of times this saved reply was sent for the current time range
top[].deltaPercent Number Change in percentage of total conversations in which this saved reply was used from the previous to current time ranges; only included if a previous time range was specified
top[].id Number This saved reply’s unique identifier
top[].mailboxId Number The unique identifier for the mailbox associated with this saved reply
top[].name String Name of this saved reply
top[].percent Number Percentage of total conversations in which this saved reply was used for the current time range
top[].previousCount Number Number of times this saved reply was sent for the previous time range; only included if a previous time range was specified
top[].previousPercent Number Percentage of total conversations in which this saved reply was used for the previous time range; only included if a previous time range was specified

Response fields

Path Type Description
count Number Number of workflows triggered in the current time range
top Array Top workflows triggered in the current range, sorted from most to least used
top[].count Number Number of times this workflow was triggered in the current time range
top[].deltaPercent Number Change in percentage of total conversations in which this workflow was triggered from the previous to current time ranges; only included if a previous time range was specified
top[].id Number This workflow’s unique identifier
top[].mailboxId Number The unique identifier for the mailbox associated with this saved reply
top[].name String This workflow’s name
top[].percent Number Percentage of total conversations in which this workflow was triggered for the current time range
top[].previousCount Number Number of times this workflow was triggered in the previous time range; only included if a previous time range was specified
top[].previousPercent Number Percentage of total conversations in which this workflow was triggered for the previous time range; only included if a previous time range was specified

Response fields

Path Type Description
count Number Number of custom fields in the report
fields Array Custom fields used in conversations from the specified date/time range
fields[].id Number This custom field’s unique identifier
fields[].name String This custom fields’s name
fields[].mailboxId Number Identifier of the mailbox where this custom field is defined
fields[].values Array Collection of all custom fields values
fields[].values[].name String Name of selected dropdown field value
fields[].values[].id Number Unique identifier of a dropdown option
fields[].values[].count Number Number of answered conversations where this custom field’s value was set
fields[].values[].previousCount Number Number of answered conversations where this custom field’s value was set in the previous date/time range
fields[].values[].percent Number Percentage of total conversations in which this custom field value was set
fields[].values[].previousPercent Number Percentage of total conversations in which this custom field value was set in the previous date/time range
fields[].values[].deltaPercent Number Percentage change between current and previous date/time range
fields[].summary Object Summary statistics
fields[].summary.total Number Total number of conversations where this custom if available.
fields[].summary.totalAnswered Number Number of conversations where this custom field has an answer/value
fields[].summary.previousTotal Number Total of conversation where this custom field could have been answered in the previous date/time range
fields[].summary.previousTotalAnswered Number Number of conversations where this custom field has an answer/value in the previous date/time range
fields[].summary.unansweredDelta Number Percentage change between current and previous date/time range for unanswered conversations
fields[].summary.unansweredPercent Number Percentage of conversations where this custom field has no answer/value
fields[].summary.previousUnansweredPercent Number Percentage of conversations where this custom field has no answer/value in the specified previous date/time range