Get queue times

The GET /queue-times endpoint gets Queue Times for an account. Queue Times include information for all interactions entering queues in an account. This information includes how long the interactions were in the queues, and why they left those queues.

Headers

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

Authorization scopes supported:

Parameters

The endpoint accepts the following query string parameters:

start

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

end

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

include

Determines which Queue Times to include in the response.

The value dictates which values are searched for within the specified time. Possible values are:

• Started. Searches for only Queue Times representing interactions that entered a queue within the specified time period.
• StartedOrEnded. Searches for Queue Times that started or ended within the specified time period.
• Processed. Searches for Queue Times representing interactions that entered the queue, started or ended, or were processed within the specified time period. Including processed time means that Queue Times representing interactions that left the queue before the specified time period may be returned.

If you plan to poll this endpoint then we recommend specifying Processed. Using Processed removes the need for any offset and ensures that you receive all data. Note, using the StartedOrEnded or Processed values can result in duplicate items being returned across search windows.

The default value is Started.

queues

A comma-delimited list of queue names. Default behavior is to return all queues.

queueType

Possible values are:

• All. Returns queues of any queue type.
• ACD. Only returns ACDs.
• Virtual. Only returns virtual queues.

The default value is ACD.

Pagination

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

Requests

Request queue times including processed

curl -L -X GET "https://***.api.newvoicemedia.com/stats/queue-times?start=2021-12-01T14:18:23.857Z&end=2021-12-11T14:18:23.857Z&include=Processed" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
-H "Accept: application/vnd.newvoicemedia.v3+json"

Request page 2 of queue times

curl -L -X GET "https://***.api.newvoicemedia.com/stats/queue-times?start=2021-12-01T14:18:23.857Z&end=2021-12-11T14:18:23.857Z&page=2" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
-H "Accept: application/vnd.newvoicemedia.v3+json"

Responses

Responses to the GET /queue-times contain a collection of Queue Time items for the specified time period. Results are sorted by the time that interactions entered queues and then queue name 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": 4,
    "pageCount": 1,
    "totalCount": 4
  },
  "items": [
    {
      "start": "2019-12-23T09:55:21.791Z",
      "interactionGuid": "016f3105-0854-43e2-9d2a-33ef02aff410",
      "medium": "Phone",
      "mediumManager": "VCC",
      "interactionPlan": "0123456789",
      "queue": "ACD1",
      "type": "ACD",
      "presentedSkills": [
        "Billing"
      ],
      "category": "Answered",
      "reason": "Delivered",
      "duration": 5189,
      "targets": null,
      "party": {
            "role": "External",
      }
    },
    {
      "start": "2019-12-23T09:55:21.791Z",
      "interactionGuid": "016f3105-0854-43e2-9d2a-33ef02aff410",
      "medium": "Phone",
      "mediumManager": "CC",
      "interactionPlan": " 0123456789",
      "queue": "VirtualQueue1",
      "type": "Virtual",
      "presentedSkills": [
        "Billing"
      ],
      "category": "Answered",
      "reason": "Delivered",
      "duration": 5189,
      "targets": {
        "targetTimeToAnswer": 5000
      },
      "party": {
            "role": "Agent",
      }
    },
    {
      "start": "2019-12-23T10:32:05.133Z",
      "interactionGuid": "016f3105-085f-4db1-be2e-b1ec61d0c6f5",
      "medium": "Phone",
      "mediumManager": "VCC",
      "interactionPlan": "0123456789",
      "queue": "ACD1",
      "type": "ACD",
      "presentedSkills": [
        "Billing"
      ],
      "category": "Breakout",
      "reason": "NoAgentsBreakout",
      "duration": 982,
      "targets": null,
      "party": {
            "role": "External",
      }
    },
    {
      "start": "2019-12-23T10:54:57.920Z",
      "interactionGuid": "016f3105-0866-463a-a9b3-16211aba205a",
      "medium": "Phone",
      "mediumManager": "VCC",
      "interactionPlan": "0123456789",
      "queue": "ACD1",
      "type": "ACD",
      "presentedSkills": [
        "Billing"
      ],
      "category": "Abandoned",
      "reason": "HangUp",
      "duration": 7044,
      "targets": null,
      "party": {
            "role": "Agent",
      }
    }
  ],
  "upTo": "2019-12-23T10:56:38.831Z",
  "latestUpdate": "2019-12-23T10:56:30.831Z"
}

Each Queue Time item in the collection contains the following parameters:

• start. The time when the interaction entered the queue. start is a UTC date in ISO 8601 format.

• interactionGuid. The unique identifier for the interaction.

• medium. The type of communication method.

• mediumManager. The origin application of the interaction, e.g. VCC (Vonage Call Centre) or VBC (Vonage Business Cloud).

• interactionPlan. The name or number of the interaction plan.

• queue. The name of the queue, as configured in the Automatic Call Distributor (ACD) or Universal Contact Distributor (UCD) applet in the Vonage Contact Center (VCC) Admin Portal.

• type. The type of queue. Possible values are: “ACD” or “Virtual”.

• presentedSkills. A comma-delimited list of presented skills.

• category. The category of reason for the interaction leaving the queue. Possible values are:

  • Answered. The interaction was connected to an agent.
  • Abandoned. The party who was queuing hung up while in the queue.
  • Breakout. Queuing was ended by the interaction triggering a breakout, either voluntarily by the queuing party, or through configured settings within the queue itself.
  • Cancelled. An agent consulting to a different queue chose to stop queuing, either by ending the consult and recalling the caller from hold, or by transferring the caller into the queue.

• reason. The reason the interaction left the queue. Possible values are dependent on category:

  • Delivered. If category is Answered, reason is always Delivered.
  • HangUp. If category is Abandoned, reason is always HangUp.
  • VoluntaryBreakout. The party who was queuing chose to leave the queue when offered to do so.
  • QueueCapacityBreakout. The queue was at the configured maximum capacity so VCC routed the interaction out of the queue.
  • QueueTimeBreakout. The interaction had queued for the maximum amount of allowed time so VCC routed the interaction out of the queue.
  • NoAgentsBreakout. No agents were available to serve the queue so VCC routed the interaction out of the queue.
  • MaxEstimatedWaitTimeBreakout. The estimated wait time for an agent to handle the interaction exceeded the configured maximum so VCC routed the interaction out of the queue.
  • AgentDeclineBreakout. The agent declined the interaction.
  • AgentTransfer. The queuing agent transferred the party on hold into the queue and left the interaction, category is Cancelled.
  • AgentRecall. The queuing agent canceled the queue event and recalled the customer, category is Cancelled.

• duration. A length of time, measured in milliseconds which indicates exactly how long the interaction spent in the queue.

• targets. A container for queue targets. Only applicable to queues with type of ‘Virtual’; for queues with type of ‘ACD’, targets is null.

  • targetTimeToAnswer. Target time to answer (TTA)—in milliseconds—associated with the queue.

• party. party contains information about which party role entered the queue:

  • role. The role of the party. Possible values are:
    • External. Most commonly indicates the customer’s channel, but any call to a number not linked to an agent will show as External.
    • Agent. Indicates the VCC agent’s channel.
    • Null. Reserved for future use.

latestUpdate

After the list of Queue Time items, the response returns a latestUpdate parameter. The value of latestUpdate is the time of the most recent event that is available using the Insights Stats API.

The difference between the current time and the latestUpdate represents the delay between an event, and the corresponding statistic being available.

We aim to minimise the delay so that the Insights Stats API data is as up-to-date as possible, but the delay may increase during busy periods or service disruption. If you require near real-time statistics, the latestUpdate value may be useful so you can respond appropriately to any delay.