Build your own reports with the API

A common use case for our API is accessing data that you need to build your own reports. There are several metrics that we display in the Intercom reporting UI that are not available via the API because they are calculated metrics. In this document, we describe those metrics and how you can calculate them yourself.

Team Performance

Conversations assigned by team

Defined as the number of unique conversations assigned to a team in the selected time period.

Search for conversations within the chosen date range and the team_assignee_id attribute.

{
    "query": {
        "operator": "AND",
        "value": [{
                "field": "created_at",
                "operator": ">",
                "value": "1666414800"
            },
            {
                "field": "created_at",
                "operator": "<",
                "value": 1673589599
            },
            {
                "field": "team_assignee_id",
                "operator": "=",
                "value": 12345
            }
        ]
    }
}

Median first response time by team assigned

The median time to reply to the first incoming message in a conversation.

Filter conversations by team_assignee_id
Find the total number of conversations using total_count
Retrieve the statistics.first_admin_reply_at value for each conversation and calculate the median of this value.

Teammate performance overview

Assigned

Filter conversations by the admin_assignee_id attribute for each teammate.
Sum the total_count of the conversations from step 1.

{
  "query": {
    "field":"admin_assignee_id",
    "operator": "=",
    "value":"5569718"  
    }
}

Participated

The number of unique conversations an admin replied to.

📘
The participated filter only shows conversations where the selected teammate(s) sent user visible replies.

Calculate this number using conversation parts:

Filter all conversation parts where part_type.author = admin and created_at is within the given date range.
Count the unique number of conversations in those parts.

{
"query":
  {
    "field":"teammate_ids",
    "operator": "=",
    "value":"5618076" 
    }
}

Replies sent

Total number of individual replies sent for all conversations within the given time period.

Calculate this number using conversation parts:

Filter all conversation parts where part_type.author = admin and created_at is within the given date range.
Calculate total number of replies.

Closed conversations

The number of unique conversations closed, filtered by the time they were closed.

📘
A single conversation can be closed multiple times.

Filter all conversation parts where part_type = close and created_at is within the given date range.
Count the unique number of conversations in those parts.

{
  "query": {
        "operator": "AND",
        "value": [
        {
                "field":"state",
                "operator": "=",
                "value":"closed" },
        {
            "field":"admin_assignee_id",
        "operator":"=",
        "value": "5565920"

        }

        ]
    }
}

Notes

Number of notes created by admin, filtered by the time they were created at.

Filter all conversation parts where part_type = note.

Assigned

Number of unique conversations assigned to each teammate, filtered by the time they were assigned at.

Calculate this number using conversation parts:

Filter all conversation parts where part_type = assigned_to is present and created_at is within the given date range.
Count the unique number of conversations in those parts.

Responsiveness

Median response time

The median of the median_time_to_reply value for each conversation.

Median response time (MRT) is defined as the median time it took for an admin to respond to a customer's last reply, at any point during a conversation, including their first response and any subsequent response.

Each individual response time for a conversation's MRT is calculated by comparing the last User response and the following admin response.

Median first response time

First response time

time_to_admin_reply

Median first response time

Median value of time_to_admin_reply across all conversations.

Time_to_admin_reply is the duration from first_contact_reply_at to first_admin_reply_at.

Median time to close

The median value of the time_to_last_close attribute for all conversations within the selected time period

📘
To calculate the time to close, we take into account when the conversation was created and the last time it was closed (in case it has been reopened and closed at some point).

Conversational Support

Proactive Support Messages

General

Any interaction a customer has with the Article Inserter or Article Search or Interacting with the Messenger or Viewing Your Help Center or Resolution Bot.

Resolved with self-serve content covers all of the above that were closed without starting a conversation with a human.

Served by a teammate after self-serve

All of the customers who participated in a Self-Serve interaction and ended up starting a conversation with a teammate.

To calculate the most popular articles read by customers (by title) you should query all articles and sort by number of views
To calculate the number of proactive messages sent you should use // TODO - Confirm this with CS // Messages (unstable API) to download CSV of all outbound sent

Effectiveness

Conversations replied to

The number of unique conversations that a teammate replied to, filtered by the time the reply was sent.

Calculate this number using conversation parts:

Filter all conversation parts where part_type = comment and created_at is within the given date range.
Count the unique number of conversations in those parts.

Conversations reassigned

Filter conversations where statistics.first_contact_reply_at is in the time range and statistics.count_assignments > 1.

{
  "query":  {
           "operator":"AND",
           "value": [
       {
         "field": "statistics.first_contact_reply_at",
         "operator": ">",
         "value": "1666414800"
       },
       {
         "field": "created_at",
         "operator": "<",
         "value": "1673589599"
       },
       {
     "field": "statistics.count_assignments",
     "operator": ">",
     "value": "1"
   }
     ]
   }
  }

Median time to first assignment

Statistics object → median of time_to_assignment value

Median time from first assignment to close

This is the duration from last_assignment_admin_reply_at to last_close_at.

Customer Satisfaction

Conversation ratings

In the Customer Satisfaction Report, conversation ratings are calculated by the date in which the conversation rating was given.

In the API, you should use created_at in the conversation_rating object of each conversation to view the date the conversation rating was given

📘
created_at returns the timestamp when the first rating was given.

Conversation Ratings by Date

{
  "query": {
  "field":"conversation_rating.replied_at",
  "operator": ">",
  "value":"1666414800"  
  }
}

Conversation Ratings by Rating Value

{
  "query":
   {
  "field":"conversation_rating.score",
  "operator": "=",
  "value":"5"
  }
}

Remarks from Customers

To access any remarks from customers, you should first retrieve the conversation, then the conversation_rating object, and finally the remark attribute for each conversation you are querying.

Conversations

New Conversations

Search for conversations with created_at within the given date range.

  "query":  {
           "operator":"AND",
           "value": [
       {
         "field": "created_at",
         "operator": ">",
         "value": "1666414800"
       },
       {
         "field": "created_at",
         "operator": "<",
         "value": "1673589599"
       }
     ]
   }

New inbound conversations

Search for conversations where source.delivered_at = customer_initiated

{
  "query":
   {
  "field":"source.delivered_as",
  "operator": "=",
  "value":"customer_initiated"  
  }
  }

Conversations replied to by teammates

Search for conversations where statistics.first_admin_reply_at is within the given date range.

📘
Conversations returned from this query may have started before the given date range.

Closed conversations

The number of unique conversations closed, filtered by the time they were closed.

Search for conversations where state = closed

{
  "query":
   {
  "field":"state",
  "operator": "=",
  "value":"closed"  
  }
}

Open conversations

The number of conversations with a status of Open at the end of the given time period.

Search for conversations where created_at is within the given date range and open = true

{
  "query":
   {
  "field":"open",
  "operator": "=",
  "value":"true"  
  }
}

Snoozed conversations

Search for conversations where created_at is within the given date range and state = snoozed

{
  "query":
   {
  "field":"state",
  "operator": "=",
  "value":"closed"  
  }
}

Reopened conversations

Search for conversations where created_at is within the given date range and statistics.count_reopens > 0

{
  "query":
   {
  "field":"statistics.count_reopens",
  "operator": ">",
  "value":"0"  
  }
  }

Additional metrics

Tagged conversations

List all tags and filter conversations by the tag_id attribute.

Single Tag Report

{
  "query":
   {
  "field":"tag_ids",
  "operator": "=",
  "value":"7020308"
  }
}

Multiple Tag Report

{
"query":
{
"field":"tag_ids",
"operator": "IN",
"value":["7020308","7538295","6927004" ]
}
}

Resolution Bot Conversations Coverage

To get a total count of Resolution Bot conversations, search for all conversations where source.delivered_as = operator_initiated and a source.body that contains the content of the Resolution Bot message.

{
  "query": {
        "operator": "AND",
        "value": [
        {
                "field":"source.delivered_as",
                "operator": "=",
                "value":"operator" },
        {
            "field":"source.body",
        "operator":"~",
        "value": "Body of first resolution bot response"

        }

        ]
    }
}