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
        }
      }
    ]
  }
}