Get agent current status

Owned by Helen Griffith
Last updated: May 21, 2024

The GET /agent-status endpoint gets information about the current status of all agents within your account. Use the endpoint independently, or in conjunction with the GET /agent-activities endpoints to provide a detailed log of all changes to an agent’s activities.

In this page


Most URLs in the example code use the following values:

Headers

Header parameters in Requests (Insights Stats API) apply to this endpoint.

Authorization scopes supported:

ScopeAccess granted
statsEntire endpoint

Parameters

Paging parameters in Requests (Insights Stats API) apply to this endpoint.

Requests

Request the current status of all agents

curl -L -X GET "https://***.api.newvoicemedia.com/stats/agent-status" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
-H "Accept: application/vnd.newvoicemedia.v3+json"

Request page 2 of agent statuses

curl -L -X GET "https://***.api.newvoicemedia.com/stats/agent-status?page=2" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
-H "Accept: application/vnd.newvoicemedia.v3+json"

Responses

Responses to the returns a list of agents and their current status. The results are ordered by agentId in ascending order.

Successful response

Success response code and parameters in Responses (Insights Stats API) apply to a successful response.

Example response

{
  "meta": {
    "page": 1,
    "count": 2,
    "pageCount": 1,
    "totalCount": 2
  },
  "items": [
    {
      "agentId": "002",
      "presence": {
        "since": "2019-12-19T16:00:23.249Z",
        "name": "Ready",
        "description": "Ready",
        "eligibleForRouting": false
      },
      "workload": {
        "since": "2019-12-19T16:05:30.212Z",
        "calls": 1,
        "semiLive": 0,
        "nonLive": 0
      },
      "interaction": [
        {
          "guid": "b6c01065-a5fa-432f-981b-649f98518878",
          "channelGuid": null,
          "since": "2019-12-19T16:05:30.212Z",
          "medium": "Phone",
          "mediumManager": "CC",
          "direction": "Outbound",
          "state": "Connected",
          "reason": null
        }
      ]
    },
    {
      "agentId": "003",
      "presence": {
        "since": "2019-12-19T16:00:30.145Z",
        "name": "Ready",
        "description": "Ready",
        "eligibleForRouting": true
      },
      "workload": {
        "since": "2019-12-19T15:49:00.512Z",
        "calls": 0,
        "semiLive": 0,
        "nonLive": 0
      },
      "interaction": []
    }
  ],
  "upTo": "2019-12-23T09:39:07.012Z"
}

Each Agent Status contains an agent ID, as defined in Vonage Contact Center Admin Portal during agent creation, in the agentId parameter. The Agent Status also contains a set of items that represent that agent’s current set of activities.

An Agent Status contains three types of activity items:

  • Presence
  • Workload
  • Interaction

An activity of Presence type contains a single item, indicating the agent’s current presence. This item consists of the following parameters:

  • since. A timestamp which indicates when the current presence started. since is a UTC date in ISO 8601 format.
  • name. The name of the presence (Ready, Away, ExtendedAway or LoggedOut). name is the same as the category on the GET /agent-activities endpoint. The following presence names are available:
    • Ready. The agent is working and capable of receiving new interactions. You can determine an agent’s actual availability from their presence in conjunction with their workload at the same time. For example, a presence of Ready and a workload containing calls: 0, semiLive: 0 and nonLive: 0 indicates that an agent is idle and therefore available.
    • Away. The agent is temporarily away and is not available to receive new interactions. Away is commonly used for activities such as breaks.
    • ExtendedAway. The agent is away for an extended period of time and is not available to receive new interactions. Extended Away is commonly used for activities such as meetings or lunch.
    • LoggedOut. The agent is logged out of ContactPad, and cannot work on interactions or receive new interactions.
  • description. Presences can be configured with description names. For example, a presence of category Away, may have a description of Lunch, or Meeting.

An activity of Workload type contains a single item, indicating the agent’s current workload. This item consists of the following parameters:

  • since. A timestamp which indicates when the current workload started. since is a UTC date in ISO 8601 format.
  • calls. The number of live interactions that the agent is currently handling.
  • semiLive. The number of semi-live interactions that the agent is currently handling.
  • nonLive. The number of non-live interactions that the agent is currently handling.

An activity of Interaction type contains a collection items. These items represent each agent’s current interactions and the states of those interactions. Each item has the following properties:

  • guid. guid is the unique identifier for an interaction.
  • since. The time when the agent started work on the interaction. since is a UTC date in ISO 8601 format.
  • medium. The type of interaction, e.g. Call or Case
  • mediumManager. The origin application of the interaction, e.g. “CC” (Vonage Contact Centre) or “UC” (Vonage Business Cloud).
  • direction. A value that indicates how the agent was involved in the interaction. Direction can be one of inbound, outbound, or internal. If the agent participated in the interaction multiple times, the activities relating to each participation may have different directions.
    • Inbound. The agent received the interaction from a queue or a cold transfer. Note that this does not include receiving a callback (see outbound) or receiving a consult (see Internal).
    • Outbound. The agent initiated an outbound interaction to an external participant or received a callback.
    • Internal. The agent received a consult from another agent or initiated an internal interaction to another agent.
  • state. The type of activity the agent was engaged in on the interaction. The possible values are:
    • Ringing. The agent was offered the interaction. For a phone call, the Ringing category describes the period in which the phone was ringing.
    • Connected. The agent was connected to the interaction. Typically the Connected category describes the period the agent was working on the interaction; for a phone call Connected is the period in which parties are connected and able to talk.
      If an agent parks a phone call, the Connected activity ends. A new Connected activity starts when the agent unparks the call.
      If a non-call interaction is interrupted by a call, the Connect activity ends. A new Connected activity starts when the interaction is resumed.
    • Wrap. The agent was in the wrap period at the end of an interaction. Wrap time is normally used for post interaction work, such as note taking.
    • Unexpected. An activity of Unexpected category usually occurs after the Ringing category. The category indicates that an agent (who was available for work) does not answer their phone, or their line is busy on another call.
    • Failed. A Failed activity can occur at any time during an interaction. Possible causes are network congestion, a fault on the line, or configuration issue.
  • reason. reason will be one of the following values (or null if any of the conditions are not met):
    • For Ringing interaction activities:
      • Monitor. The user is monitoring the interaction.
    • For Connected interaction activities:
      • Resumed. The agent was reconnected to the interaction when it was resumed from being interrupted.
      • Unparked. The agent was reconnected to the interaction after it was unparked.
      • Monitor. The user is monitoring the interaction.
    • For Wrap interaction activities:
      • Monitor. The user is monitoring the interaction.
    • For Unexpected interaction activities:
      • NumberBusy. The agent being called declined the call or is busy. For a phone call NumberBusy indicates that the agent is already connected to another call, or rejected the call.
      • NoAnswer. A Ringing interaction activity was never answered, or was rejected, and eventually timed out.
      • NumberUnobtainable. The target number could not be reached.
      • CallRejected. The connection was rejected at some point while trying to connect.
      • CallFailed. Exact cause is undetermined.
      • ConnectionUnavailable. While trying to connect the call to the agent, the agent's connection to required media — such as WebRTC — was not available.
    • For Failed interaction activities:
      • NumberUnobtainable. The target number could not be reached.
      • CallRejected. The connection was rejected at some point while trying to connect.
      • CallFailed. Exact cause is undetermined.


Try it out

  

For information, see Trying out Vonage Contact Center APIs.