How to get KPIs and metrics from the Helpscout API

Helpscout is a customer service platform providing email support, live chat, and knowledge base tools, designed to help teams manage customer inquiries and improve communication with a modern OAUTH API giving you access to your ticket data. You can find their documentation here: Helpscout's API.

Authentication

Helpscout uses OAuth 2.0 authorization. When fetching data for your own account, creating a new app (under Your Profile > My Apps > Create My App) and using the App ID and App Secret is sufficient to use the Client Credentials Flow to get an access token which you will then provide as a Bearer token to any endpoints.

To get a token POST the following JSON request to https://api.helpscout.net/v2/oauth2/token:

{
  "grant_type": "...",
  "client_id": "...",
  "client_secret": "..."
}

Contents

• Endpoint
• How to get ticket count metrics from Helpscout

Endpoint

Helpscout offers various endpoint but to extract ticket statistics and metrics you use the Mailbox 2.0 API conversations endpoint at https://api.helpscout.net/v2/conversations.

How to get ticket count metrics from Helpscout

Helpscout doesn’t offer an aggregation endpoint but rather you will request all tickets in a certain time period and count the results.

For these requests the optional mailbox parameter is the id of the mailbox you want to get the conversations for. You can get this from your Mailboxes endpoint.

https://api.helpscout.net/v2/conversations?
  // Replace this with the id of the site
  &mailbox=123
  // See options below
  &status=all
  &sortField=createdAt
  &sortOrder=desc
  &query=(createdAt:[2024-01-01T00:00:00Z TO 2024-01-31T23:59:59Z])

Options for parameters:

• status: if calculating metrics by created_at you want to set this to all to not hide any closed tickets from the response
• query: specify the dates you want to get metrics including the timezone, see here for more query options

Conversations Results

The endpoint will return the following data:

{
  "_embedded": {
    "conversations": [
      {
        "id": 10,
        "status": "closed",
        "mailboxId": 13,
        "createdAt": "2012-03-15T22:46:22Z"
      },
      ...
    ]
  },
  "_links": {
    "next": {
      "href": "..."
    }
  },
  "page": {
    "size": 25,
    "totalElements": 0,
    "totalPages": 0,
    "number": 0
  }
}

Each request will contain at most 25 items and you can retrieve further pages by using the next.href value from the response to request the next page continuosly.

Calculating support ticket metrics

Simply count the number of conversations returned across all pages in the requested timeperiod.