Get agent summaries

The GET /agent-summaries endpoint gets information about an agent’s activities aggregated over a period of time. This information is typically aggregated into 15 minute chunks. If you require different aggregation periods, contact your account manager. This endpoint is predominantly for use by Work Force Management (WFM) integrations and only returns data if enabled for your account.

Parameters

The endpoint accepts the following query string parameters:

start

Type Required Example
Date True 2019-12-20T15:42:39.825Z

The start date and time of the search window. Use ISO 8601 format.

If you plan to poll this endpoint, we recommend that you set start to the value returned in the upTo parameter in the previous request’s response. For more details, see the FAQ page.

end

Type Required Example
Date False 2019-12-20T15:47:39.825Z

The end date and time of the search window. Use ISO 8601 format. Default is now.

cadence

Type Required Example
Double True 15

Determines the period of time, in minutes, of agent information that each Agent Summary item represents. The default is 15. Currently the only possible value is 15. If you require a different cadence, contact your account manager.

agentId

Type Required Example
String False 1234

Specify an agent id to limit the response to include information about only the specified agent.

Pagination

Paging parameters apply to this endpoint.

Responses

Responses to the GET /agent-summaries returns a collection of Agent Summary items. Items are sorted by timestamp in descending order.

Successful response

Success response code and parameters apply to a successful response.

Example response

{
  "meta": {
    "page": 1,
    "count": 1,
    "pageCount": 1,
    "totalCount": 1
  },
  "items": [
    {
      "agentId": "1234",
      "timestamp": "2019-12-23T09:45:00Z",
      "interactions": {
        "handleTime": [
          {
            "type": "Ringing",
            "totalTime": 3769,
            "inbound": 3769,
            "outbound": 0,
            "internal": 0
          },
          {
            "type": "Connected",
            "totalTime": 51768,
            "inbound": 51768,
            "outbound": 0,
            "internal": 0
          },
          {
            "type": "Wrap",
            "totalTime": 4105,
            "inbound": 4105,
            "outbound": 0,
            "internal": 0
          }
        ],
        "offered": [
          {
            "type": "Answered",
            "count": 1,
            "inbound": 1,
            "outbound": 0,
            "internal": 0
          }
        ],
        "actions": []
      },
      "presence": {
        "states": [
          {
            "type": "Ready",
            "totalTime": 825407,
            "count": 1
          },
          {
            "type": "Away",
            "totalTime": 10493,
            "count": 1
          },
          {
            "type": "LoggedOut",
            "totalTime": 4454,
            "count": 1
          }
        ]
      }
    }
  ],
  "upTo": "2019-12-23T09:59:32.421Z",
  "cadence": 15
}

Each Agent Summary item contains the following parameters:

  • agentId. The id of the agent.

  • timestamp. A timestamp indicating the start of the aggregated period of time. If the cadence is set to 15 this will be either on the hour, quarter past, half past, or quarter to the next hour. timestamp is a UTC date in ISO 8601 format.

  • interactions. Contains details about the interactions the agent was involved with during the time period:

    • handleTime. Contains information about the amount of time the agent spent on interactions in the following states:
      • Ringing. The amount of time the agent spent on interactions that were in the Ringing state. Ringing is further broken down by the direction of the interaction.
      • Connected. The amount of time the agent spent on interactions that were in the Connected state. Connected is further broken down by the direction of the interaction.
      • Wrap. The amount of time the agent spent on interactions that were in the Wrap state. Wrap is further broken down by the direction of the interaction.
      • HeldExternalParty. The amount of time external parties spent in the Held state having been placed there by the agent. HeldExternalParty is further broken down by the direction of the interaction. Note, this is a subset of the Connected value.
    • offered. Contains information about the how the agent responded to interactions they were offered.
      • Answered. Contains a count of interactions offered to the agent that they answered. Answered is further broken down by the direction of the interaction.
      • Unexpected. Contains a count of Unexpected failed interactions offered to an agent—this is most commonly due to agent behaviour such as not answering the phone. Unexpected is further broken down by the direction of the interaction.
      • Failed. Contains a count of failed interactions offered to an agent—this is caused by a failing in the system such as a telephony provider failure. Failed is further broken down by the direction of the interaction.
    • actions. Contains information about any actions undertaken by the agent took during the time period.
      • HoldExternalParty. Contains a count of the number of times the agent placed an external party on hold. HoldExternalParty is further broken down by the direction of the interaction.
  • presence. Contains details about the presence the agent was in during the time period:

    • states. Contains information about the amount of time the agent spent in the following states:
      • Ready. The agent is working and capable of receiving new interactions.
        • totalTime. Total time spent in a Ready state for the specified aggregation period.
        • count. Number of times the agent went into the Ready state for the specified aggregation period.
      • Away. The agent is temporarily away and is not available to receive new interactions. A presence of Away commonly indicates activities such as breaks.
        • totalTime. Total time spent in an Away state for the specified aggregation period.
        • count. Number of times the agent went into the Away state for the specified aggregation period.
      • ExtendedAway. The agent is away for an extended period of time and is not available to receive new interactions. A presence of ExtendedAway commonly indicates activities such as meetings or lunch.
        • totalTime. Total time spent in an ExtendedAway state for the specified aggregation period.
        • count. Number of times the agent went into the ExtendedAway state for the specified aggregation period.
      • LoggedOut. The agent is logged out of ContactPad, and cannot work on interactions or receive new interactions. Note, agents that have never logged into the system will not appear.
        • totalTime. Total time spent in a LoggedOut state for the specified aggregation period.
        • count. Number of times the agent went into the LoggedOut state for the specified aggregation period.

The response also contains the following meta data:

  • cadence. Indicates the time period covered by the response data.