The A-Z of Webex Contact Center APIs: Agents

Welcome to the second installment of our blog series, “The A-Z of Webex Contact Center APIs”. In this series we are covering the entirety of the RESTful APIs available for the Webex Contact Center, providing insights into their execution and impact from a user's perspective. In this edition we will be going over the Agents APIs, Webhooks, and the use cases that drive their engagement by Webex Contact Center developers.

Webex Contact Center Agents

An agent is a person who works in a contact center and serves as an interface between customers and businesses. Agents are the most frequent human contact a customer has with a business for solving problems, placing orders, or answering questions about related products and services. Agents can interact with customers using the Webex Contact Center via various channels like voice, instant messaging, Facebook Messenger, WhatsApp, SMS, Email, and more.

Agents utilize many tools while being effective at managing customer inquiries. These tools include CRM (Customer Relationship Management) software, help desk software, SMS management tools, telephones, soft phones, computers, wallboards, predictive dialers and customer satisfaction surveys. Though the Webex Contact Center Agent Desktop consolidates many of these tools into one place, developers are encouraged to use the available developer toolsets to enhance the agent experience.

The Agent Desktop

The Webex Contact Center Agent Desktop is where agents receive and manage interactions with business customers. They can handle tasks like calls, chats, emails, and more all from one interface in the browser. Agents can access the Desktop and assist customers remotely if they have access to a browser and credentials for their Webex agent user account. They have access to many of the tools mentioned above in the form of custom widgets or out of the box set setup.

Custom Agent Desktop with Webex Contact Center RESTful APIs

Third-party developers have been successful at using the available Webex Contact Center RESTful APIs to build custom desktop experiences and CTI (Computer Telephony Integration) connectors that work in a CRM or support tools. For example, Consilium's UniAgent for Zendesk solution allows Webex Contact Center Agents to use the Webex Contact Center agent desktop functionality with a custom version of the desktop embedded in Zendesk. This is done through a combination of a custom headless widget and Webex Contact Center integration.

A subset of the Agents APIs can be used to develop these kinds of integrations, and below we will be going over them and how to get started building custom solutions.

The Agents REST APIs

Above, an agent is described as a person that works in a contact center. In the context of the APIs, the Agent resource encapsulates the entities that handles Tasks through interactions with customers. Webex Contact Center Administrators and Supervisors can also carry the role of an Agent and trigger the Agents APIs. Agents can be humans or bots operating via the APIs.

Get Agent Activities

https://developer.webex-cx.com/documentation/agents/v1/get-agent-activities

The Get Agent Activities API can be used to get all Agent activities created after a given timestamp epoch. The API returns JSON objects sorted by start time and can be filtered by agent id, team id, and channel type. This API can be used in a reporting tool or confirm findings in a reporting tool. It requires an administrators access token and the scope cjp:config_read.

Buddy Agent List

https://developer.webex-cx.com/documentation/agents/v1/buddy-agents-list

The Buddy Agent List API produces a list of agents in a given state and media according to an agent profile setting. In the agent desktop the agent can request a consult or transfer a customer to an available agent based on status. Developers can mimic that behavior using this API and allow agents to set values in a custom input for the media type (Telephony, chat, social, email) or state (Available, Idle) parameters in the API call's request body before producing a list of available agents to transfer or consult with.

Login

https://developer.webex-cx.com/documentation/agents/v1/login

The Login API is used to log an agent into the Webex cloud. The Login process makes an agent active and visible to administrators and supervisors who use tools like Analyzer and the Supervisor Desktop to monitor how many agents are online and available to assist customers. This process is not to be confused with the OAuth 2.0 flow that is required for users to authorize integrations in the previously mentioned custom desktop integrations.

You can see from the above photo of the supervisor agent view (see the agent view below) that after the agent authenticates via Webex, they have included the role, dial number/extension, and team which map to parameters that are included in this APIs request body.

Logout

https://developer.webex-cx.com/documentation/agents/v1/logout

Logout is the programmatic inverse of login. We are telling the Webex cloud that we are disconnecting and that as an agent, we are no longer available to assist customers. This option is also available when clicking on the icon in the top right corner of the cloud-based Webex Contact Center agent desktop application. The API does require a logout reason in the request body.

Reload

https://developer.webex-cx.com/documentation/agents/v1/reload

When developers are building custom desktops, we have to think about times where we lose network connectivity. This API helps agents re-establish the lost connection to the Webex Cloud session/agent desktop without having to go through the login process to establish a new connection.

State Change

https://developer.webex-cx.com/documentation/agents/v1/state-change

This API allows the user to toggle between states (Available, Idle). The request body requires a State (Available or Idle) which can be provided via an input from the user, and an Auxiliary Code which can be obtained by listing out the Auxiliary Codes from the API.

Get Agent Statistics

https://developer.webex-cx.com/documentation/agents/v1/get-agent-statistics

This API is going to give stake holder several stats on agents in a given time period. Administrators and Supervisors are going to know answers to questions like how many customers an agent handled, how many customers were offered to an agent, how many of those customers were rejected by an agent, how many times did an agent transfer a customer, etc. This is a good API for reporting tools.

Webhooks

The Agents API also has associated Webhook events. The events are triggered by Agent Login, Agent Logout, and Agent State Change. The Webhooks require cjp:config, cjp:config_read.

WebSocket Option

Your application can receive notifications during operations like Agent Login, Agent Logout, and Agent State Change by registering a bi-directional WebSocket Connection with the Subscribe Notification API. This API can be used with an integration that is scoped for cjp:user.

This information is important in the context of this API. When developing a custom desktop, if a developer wants to include webhooks, the Agent State Change API, and necessary Auxiliary Codes API, they will need to include an onboarding step that allows an administrator with permissions to read configurations to authorize the application through the OAuth 2.0 flow for setup. Alternatively, the developer can use the Agent State Change API, or Webhooks, and set up a WebSocket connection with an Agent token. See this sample starter code with values hard coded. Developers can choose the path forward given the above information.

Need Some Help? We Got You Covered!

We are excited to provide you with support for these features. If you need help, the Webex Developer Support Team is standing by and happy to assist. You can also start or join a conversation on the Webex for Developers Community Forum.