FAQ (Insights Stats API)

1 I see Busy in ContactPad. Why is that not reflected by the Insights Stats API?
2 How do I know if an agent is Ready and Idle, or Ready and Busy/Working?
3 How do I know when a call was transferred?
4 How do I determine login time?
5 How do I identify Call Connect Router channels?
6 What is the best practice for using the Insights Stats API?
- 6.1 Authentication and regional access
- 6.2 Time range management
- 6.3 Pagination
- 6.4 Recommended endpoints for agent activity
- 6.5 Performance
7 Internal Server Error

I see Busy in ContactPad. Why is that not reflected by the Insights Stats API?

The Insights Stats API returns Agent Activity and Agent Status resources, which provide a more detailed view of an agent's presence and each individual interaction state than the simplified status displayed in ContactPad. For more information about these resources, see Resources (Insights Stats API).

For example, with an omni-channel solution, an agent can work on a chat interaction and wrap up an outbound call at the same time. The Insights Stats API reports the agent's presence as Ready (online), the chat has an interaction state of Connected, and the outbound call has an interaction state of Wrap Up.

The WFM Agent State resources returned by the GET /wfm/agent-states endpoint combine presence and workload information into a single state for an agent. This is similar to the simplified status displayed in ContactPad. For more information about WFM Agent States, see Workforce Management (WFM).

How do I know if an agent is Ready and Idle, or Ready and Busy/Working?

Look at both the agent's presence and interaction states. The following example shows a response from the GET /agent-status endpoint:

{
  "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": true
      },
      "workload": {
        "since": "2019-12-19T16:05:30.212Z",
        "calls": 1
      },
      "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
      },
      "interaction": []
    }
  ],
  "upTo": "2019-12-23T09:39:07.012Z"
}

Agent 002 has a presence of Ready but has an interaction in the Connected state, so the agent is busy. Agent 003 has a presence of Ready and no interactions, so the agent is idle. A more complex response may contain many interactions of different media types or states.

Use this approach to define what constitutes a busy state. For example, you may choose to treat an agent with all interactions in the Wrap Up state differently from an agent who is actively connected.

How do I know when a call was transferred?

The API does not explicitly record a transfer event. To identify when a transfer occurred, examine the channel details on the Interactions endpoints. The transfer sequence is visible from when the second agent's channel connects and when the first agent's channel closes.

When the first agent consults a second agent, the first agent's channel remains open while the new agent's channel connects. When the first agent transfers the call, the first agent's channel closes, but the second agent's channel and the external party's channel remain connected.

The following example shows an interaction transferred from agent 01 to agent 002. The events arrays are abbreviated. See Get interactions for the full response structure.

{
  "status": "Completed",
  "medium": "Phone",
  "mediumManager": "CC",
  "start": "2020-01-10T11:13:05.836Z",
  "guid": "016f8db7-798f-407c-9925-ef8c2b51e6b0",
  "conversationGuid": "0044a6da-f741-4a9f-ad74-2b0fff6d052a",
  "duration": 87028,
  "direction": "Inbound",
  "serviceName": "Report Gp 2",
  "connectTo": "02034631242",
  "connectFrom": "01256700817",
  "interactionPlanMapping": {
    "addressName": "Main Support Number",
    "mappingName": "Mapping1",
    "interactionPlanName": "Customer Support Plan"
  },
  "channels": [
    {
      "guid": "016f8db7-798f-407c-9925-ef8c2b51e6b0",
      "offset": 0,
      "duration": 84646,
      "endReason": "Released",
      "party": { "id": null, "role": "External", "touchpoint": "01256700817" },
      "events": []
    },
    {
      "guid": "45f4ee27-a4ae-4530-ba04-3fdb2cab2cc2",
      "offset": 6721,
      "duration": 51897,
      "endReason": "Released",
      "party": { "id": "01", "role": "Agent", "touchpoint": "07760255435" },
      "events": []
    },
    {
      "guid": "b805b718-569e-447c-8252-15678e855cd8",
      "offset": 30239,
      "duration": 56789,
      "endReason": "Released",
      "party": { "id": "002", "role": "Agent", "touchpoint": "07760274856" },
      "events": [ ... ]
    }
  ]
}

How do I determine login time?

A login event occurs when an agent transitions from Logged Out to any other presence state. If an agent does not set their presence to Logged Out at the end of a session, the API cannot determine the login time for the following session.

How do I identify Call Connect Router channels?

Identify Call Connect Router (CCR) channels using the party.id property of the channel. For a CCR channel, id is set to CCRConnect.

CCR channel availability

CCR channels only appear in the API response after the interaction has completed. They are not available while the interaction is in progress.

What is the best practice for using the Insights Stats API?

Authentication and regional access

Use the correct regional endpoint for your deployment. The following table lists the available endpoints.

Region	Base URL

Region	Base URL
EMEA	`https://emea.api.cc.vonage.com/`
USA	`https://nam.api.cc.vonage.com/`
APAC	`https://apac.api.cc.vonage.com/`

Include a bearer access token with the stats scope in the Authorization header of every request. For more information, see Authentication (Insights Stats API).

Time range management

The API Gateway applies a 10-second timeout. To avoid gateway timeouts, keep request windows short. Follow these guidelines when configuring time ranges:

Limit each request window to a maximum of 24 hours.
Use ISO 8601 format for the start and end parameters.

Pagination

Set limit=500 for the optimal page size per request. This value balances response size against the number of API calls required to retrieve a full data set. For more information about pagination parameters, see Requests (Insights Stats API).

Recommended endpoints for agent activity

The following endpoints are recommended for retrieving agent activity data:

GET /agent-activities — returns a comprehensive view of an agent's presence, workload, and interaction activities.
GET /wfm/agent-states — returns presence and workload combined into a single state sequence, optimized for Workforce Management (WFM) integrations.

To reduce response volume, apply the following filters where appropriate:

Filter by agentId to target a specific agent.
Filter by activity type (presence, workload, or interaction) to limit the data returned.

Workload activities include metrics for calls, semiLive, and nonLive interactions.

Performance

For high-volume accounts, divide large requests into smaller time-window chunks to avoid timeouts. Apply the following practices:

Monitor for HTTP 504 errors and reduce the request window size if they occur.
Implement error handling for request timeouts, rate limiting, and authentication failures.

Internal Server Error

An Internal Server Error can occur for several reasons, including an unusually complex call plan that generates a large number of routing events. Check your call plan configuration for routing loops or repeated sequences if you see interactions with status: InternalError.

Example: when this may happen

An Internal Server Error can occur when a single interaction generates more than 500 applet events or exceeds 250 routing rebuilds.