Legacy Mailbox API 1.0 is deprecated
Legacy Mailbox API 1.0 was deprecated on November 20, 2019. Please use Mailbox API 2.0 going forward. If you have any questions or need help with the new API, please reach out.
Conversations Report
- REST Method: GET
- URLs: https://api.helpscout.net/v1/reports/conversations.json
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.
URL Parameters
A variety of filters are available as query parameters. Including any of these will result in only conversations that match the filters being included in the report.
| Parameter | Type | Required | Example |
|---|---|---|---|
| start | Date/Time (ISO 8601, in UTC) | Yes | 2015-01-01T00:00:00Z |
| end | Date/Time (ISO 8601, in UTC) | Yes | 2015-01-31T23:59:59Z |
| previousStart | Date/Time (ISO 8601, in UTC) | No | 2014-01-01T00:00:00Z |
| previousEnd | Date/Time (ISO 8601, in UTC) | No | 2014-01-31T23:59:59Z |
| mailboxes | list of mailbox identifiers | No | 1,2,3 |
| tags | list of tag identifiers | No | 1,2,3 |
| types | list of conversation types (email, chat, or phone) | No | email,chat |
| folders | list of folder identifiers | No | 1,2,3 |
Response
| Response | Name | Type | Notes |
|---|---|---|---|
| Header | Status | Int | 200 |
| Body | filterTags | Collection | All tags available for filtering in reports, including tag id=1, which represents conversations that are untagged |
| companyId | Long | ||
| 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. | |
| busiestTimeStart | Int | Starting hour of the busiest time range, in the company's time zone | |
| busiestTimeEnd | Int | Ending hour of the busiest time range, in the company's time zone | |
| current | Time Range Statistics (Conversations) | Statistics about conversation volume for the current time range | |
| previous | Time Range Statistics (Conversations) | Statistics about conversation volume for the previous time range; only included if a previous time range was specified | |
| delta | Multiple Time Range Statistics (Conversations) | Statistics showing how conversation volume changed between two time ranges; only included if a previous time range was specified | |
| tags | Tag Statistics | Statistics about the most popular tags | |
| customers | Customer Statistics | Statistics about the most active customers | |
| replies | Saved Reply Statistics | Statistics about the most frequestly used saved replies | |
| workflows | Workflow Statistics | Statistics about the most frequently used workflows | |
| customFields | Custom fields Statistics | Statistics about the most frequently used custom fields |
Example Response
{
"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
}
}
]
}
}