Unique Integration APIs

When integrating workforce management with our contact center platform, you may also want to connect to our RingEX platform. For example, agents may have a need to contact other employees who are not agents and are part of the back office. Those employees will have a RingEX account and you'll need the RingCentral user ID to lookup the address book and find contacts that are only in the back office. In those cases, you need a mapping between the RingCentral user ID and RingCX agent ID.

User List

The public user list most developers will use has many details including creation date, enabled status, and roles. However, for integrations, a smaller set of user data may be all that is needed, but with the added ability to distinguish the RingCX user name from the RingCentral user name and the environment ID. For this purpose, there's an integration user list that can be used instead.

Sub-Accounts

Each main account has a sub-account where most customers reside. However, for partners, more sub-accounts may exist and retrieving sub-accounts may be useful for determining which account is being used by the customer.

Agents

Most developers will want a list of agents and agent groups, but for workforce management, there are additional details that are important to know about agents. Agents are derived from RingEX users and the RingCentral User ID will map to an agent ID in RingCX. Along with this detail, you can also retrieve the agent's supervisors as an array of agent IDs, or if the agent is a supervisor, a list of agents that the agent supervises (superviseeAgentIds).

Queue Groups

Once known as gates, queues are inbound routing rules for customers calling in to a number. Typically, queues have agents assigned to them and each queue would have to be iterated through to find all the agents assigned to a queue group. However, the gate group with agents integration API allows you to get a complete list of all queues in a queue group and the agents contained in that queue in a single call.

Integration Reports

The integration reports are special reports for integration purposes to assist with better workforce management. The integration reports consists of the following reports for agent and queue statistics.

• Agent Extended Statistics Report - An extended agent and queue report with call counts and durations
• Agent Segment Metadata Report - A detailed agent interaction report by segment for each call
• Queue Statistics Report - A specific report that lists all the queues in a queue group and the agents within each queue.

Agent Extended Statistics Report

The report file can be in either CSV or XML format. The table below explains the fields of each interval.

Agent Segment Metadata Report

Also known as the interaction metadata report, this report is broken down into call legs, or also known as segments. Each segment consists of an interaction between a single agent and client. Each client could have have multiple segments as they are transferred to different agents, but each agent has only a single segment with a client.

POST https://{BASE_URL}/voice/api/integration/v2/admin/reports/accounts/{subAccountId}/interactionMetadata

Request Body

Quick example: let's say we want to find the report with call start time 2022-10-20T07:47:48, we'll have segmentEndTime < 2022-10-20T07:47:48 < segmentEndTime + timeInterval (assuming no time zone offset). So a valid set of values for request body will be:

{
    "segmentEndTime": "2022-10-20T07:40:00",
    "timeInterval": 600,
    "timeZone": "US/Eastern"
}

Response

Queue Statistics Report

The report file can be in either CSV or XML format. The table below explains the fields of each interval.