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 |