As part of our ongoing investments in the performance and intuitiveness of Front analytics, the analytics feature was revamped earlier this year. As part of that revamp, we have deprecated the endpoints that supported the legacy analytics, in favor of new endpoints that align with the latest capabilities of the analytics feature. The deprecated routes will be removed on June 24th, 2022.

Overview

If you or your team are using any of the following endpoints, you’ll want to migrate to the new endpoints before the then:

Analytics

• GET /analytics
• GET /teams/{team_id}/analytics

Exports

• GET /exports
• POST /exports
• POST /teams/{team_id}/exports
• GET /exports/{export_id}

We’ll walk through the specific changes for each endpoint and the recommend migration strategy in more detail below.

Analytics reports

At a high level, instead of requesting analytics with GET /analytics or GET /teams/{team_id}/analytics, you should instead create a report first via POST /analytics/reports and then fetch the report via GET /analytics/reports/{report_uid}.

The exact specifics of the schema for requests/responses using these new endpoints should be viewed on the relevant API documentation, but there a few high level changes to call out:

• report parameters are now passed via the request body, rather than query parameters
• metrics will no longer be computed both for the requested time period and the previous time period (a block of time the same length as that explicitly requested, immediately preceding it). Two requests can be made to obtain the same results, if needed.
• analytic reports are now computed with a day interval with a minimum of a 1-day range. The start and end properties respectively represent timestamps for the start and end of the day.
  • start is rounded down to the start of the day in the specified timezone.
  • end is rounded up to the end of the day in the specified timezone.
• inbox, tag, and teammate IDs that were previously passed as query parameters are now consolidated into the filters body property
• only scalar metrics are available: table and “time graph” metrics are no longer supported. Multiple requests can be made to compute values over time
• the new set of available metrics is now:
  • avg_first_response_time
  • avg_handle_time
  • avg_response_time
  • avg_sla_breach_time
  • avg_total_reply_time
  • new_segments_count
  • num_active_segments_full
  • num_archived_segments
  • num_archived_segments_with_reply
  • num_csat_survey_response
  • num_messages_received
  • num_messages_sent
  • num_sla_breach
  • pct_csat_survey_satisfaction
  • pct_tagged_conversations
  • num_open_segments_start
  • num_closed_segments
  • num_open_segments_end
  • num_workload_segments

Example

We’ll walk through an example of requesting the avg_first_response_time for a particular inbox and time in the deprecated and new endpoints.

Deprecated endpoint

1. Request analytics

curl --request GET \
     --url 'https://api2.frontapp.com/analytics?start=1631397600&end=1632002399&timezone=Europe%2FParis&inbox_ids=inb_1&metrics=avg_first_response_time \
     --header 'Accept: application/json'

2. A response like the following would be received

{
  "_links": {
    "related": {
      "owner": "https://api2.frontapp.com/teams/tim_1"
    }
  },
  "status": "pending",
  "progress": 0,
  "metrics": [
    {
      "id": "avg_first_response_time",
      "metric_type": "scalar",
    }
  ]
}

3. The same request as in step 1 would be re-submitted until progress has reached 100:

{
  "_links": {
    "related": {
      "owner": "https://api2.frontapp.com/teams/tim_1"
    }
  },
  "status": "done",
  "progress": 100,
  "metrics": [
    {
      "id": "avg_first_response_time",
      "metric_type": "scalar",
      "t": "dur",
      "p": 123,
      "v": 456
    }
  ]
}

New endpoint

1. Create a new report

curl --request POST \
     --url https://api2.frontapp.com/analytics/reports \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data-raw '{ "start": 1631397600, "end": 1632002399, "timezone": "Europe/Paris", "filters": { "inbox_ids": [ "inb_1" ] }, "metrics": ["avg_first_response_time"] }'

2. A response like the following will be received:

{
  "_links": {
    "_self": "https://api2.frontapp.com/analytics/reports/123abc"
  },
  "status": "running",
  "progress": 0,
  "metrics": []
}

3. A GET request should be made to the _links._self to fetch the report again, until progress has reached 100:

{
  "_links": {
    "self": "https://api2.frontapp.com/analytics/reports/123abc"
  },
  "status": "done",
  "progress": 100,
  "metrics": [
    {
      "id": "avg_first_response_time",
      "type": "duration",
      "value": 456
    }
  ]
}

Analytics exports

We can summarize the changes to the exports endpoints as follows:

Again, the specific schemas for requests/responses using these new endpoints should be viewed on the relevant API documentation, but there a few high level changes to call out:

• exports are now computed with a day interval with a minimum of a 1-day range. The start and end properties respectively represent timestamps for the start and end of the day.
  • The start is rounded down to the start of the day in the specified timezone.
  • The end is rounded up to the end of the day in the specified timezone.
• the filters work identically to those for analytics reports, which means it’s possible to filter by team, channel, teammate, inbox, or tag
• the export type must be defined either events or messages (previously determined by should_export_events)

Example

We’ll walk through an example of requesting an export for a particular inbox using the deprecated and new endpoints.

Deprecated endpoints

1. Create the export

curl --request POST \
     --url https://api2.frontapp.com/exports \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data-raw '{ "start": 1631397600, "end": 1632002399, "timezone": "Europe/Paris", "inbox_id": "inb_1" }'

2. Fetching the export metadata (GET /exports/{export_id}) will eventually return:

{
  "_links": {
    "self": "https://api2.frontapp.com/team/tim_1/exports/exp_3f",
    "related": {
      "owner": "https://api2.frontapp.com/teams/tim_1"
    }
  },
  "id": "exp_3f",
  "status": "done",
  "progress": 100,
  "url": "https://url.to.download.from/front/123",
  "filename": "file.csv",
  "size": 1,
  "created_at": 1634818974,
  "query": {
    "inbox_id": "inb_1"
    "start": 1631397600,
    "end": 1632002399,
    "timezone": "Europe/Paris",
    "should_export_events": false,
    "should_include_private_inboxes": false,
    "columns": [
      "Message ID"
    ]
  }
}

New endpoints

1. Create the export

curl --request POST \
     --url https://api2.frontapp.com/analytics/exports \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data-raw '{ "type": "messages", "start": 1631397600, "end": 1632002399, "timezone": "Europe/Paris", "filters": { "inbox_ids": [ "inb_1"] } }'

2. Fetching the export metadata (GET /analytics/exports/{export_id} will eventually return:

{
  "_links": {
    "self": "https://api2.frontapp.com/analytics/exports/456"
  },
  "status": "done",
  "progress": 100,
  "url": "https://url.to.download.from/front/456",
  "filename": "file.csv",
  "size": 1,
  "created_at": 1634818974,
  "filters": {
    "inbox_ids": [ "inb_1" ]
  }
}

If you have any questions or concerns, please don't hesitate to reach out on the Front Community.