Determining agent availability when escalating from advanced AI agents

What's my plan?

Add-on | AI agents - Advanced

The availability check described in this article should be used only with CRM integrations other than Zendesk. To check Zendesk agent availability, see Checking operating hours and agent availability during conversations with advanced AI agents instead.

When using an advanced AI agent for customer support, it’s helpful to know when a human agent is available to step in. The Agent Availability API helps with this by allowing your AI agent to check the availability of specific agents or groups of agents based on certain criteria.

The API provides detailed information about each agent’s status, including whether they’re online, away, or offline for different channels like messaging. It also shows their overall availability across all channels, the tasks they’re currently handling, and their workload limits for specific channels.

By using the Agent Availability API, you can make your AI agent smarter when it comes to handing off conversations, routing customer queries to the right agent, or tracking agent availability or estimated wait times.

In this article, we’ll show you how to set it up so your AI agent and support team can work together more efficiently, giving customers faster and more precise help.

This article contains the following topics:

Prerequisites for setting up the Agent Availability API in the integration builder

Creating a token to access the API

Creating the integration in the integration builder

Prerequisites for setting up the Agent Availability API in the integration builder

To set up the Agent Availability API in the integration builder, you'll need to gather the following key information:

The Zendesk subdomain. This is the name of your company within your Zendesk instance. This is needed for the URL to make the call to the API using the integration builder.

Auth token and an admin email. Created in Admin Center, this token will authorize your AI agent to make the request for the Agent Availability data.

Any group ID (if applicable). If you want to filter for online agents belonging to a specific group, you can do so with a URL query.

Creating a token to access the API

To access the Zendesk API, you'll need to create a token in Admin Center.

To create an API token

In Admin Center, click Apps and integrations in the sidebar, then select APIs > Zendesk API.

Click Add API token.

Give the token a descriptive name, such as Agent Availability.

Copy the token somewhere safe, as you'll need this for setting up the integration in the integration builder.

Creating the integration in the integration builder

Create an integration in the integration builder.

Go to the Environment tab and select your chosen environment (for example, Production, or you could change this to something more descriptive such as getAgents).

Set up the endpoint using the following format, replacing [your-subdomain] with your subdomain:
https://[your-subdomain].zendesk.com/api/v2/agent_availabilities

(Optional) Further customize the query URL by filtering.

Example 1: If you want to check how many agents are online now in the messaging channel:
https://[your-subdomain].zendesk.com/api/v2/agent_availabilities?filter[channel_status]=messaging:online

If you want to check for agents available online and in a specific service group:
https://[your-subdomain].zendesk.com/api/v2/agent_availabilities?filter[channel_status]=messaging:online&filter[group_id]={{groupId}}
For more information, see Agent Availability API.

On the Authorization tab, set the Authorization type to Basic Auth.

Username: Your admin email address with ‘/token’ appended (for example, admin@yourcompany.com/token).

Password: Paste the API key you generated earlier in Admin Center.

On the Headers tab, click Add Header.

In the Key field, enter Authorization.

In the Value field, enter Basic {{apiToken}}.

(Optional) If you're checking for a particular groupId, then you can either add it statically to the URL query or you can create a dynamic link by creating a parameter in Request parameters with a key such as groupId and adding &filter[group_id]={{groupId}} to the URL (as demonstrated in step 4).

With that all set up, you should be able to successfully test your integration to view the response.

For the success scenario, you can now add your session parameters. Here are three commonly useful example parameters:

agentCheck: Provides an array of relevant available agents.

In the dialogue builder, use a conditional block with Includes.

availableAgent: Provides number of relevant available agents.

In the dialogue builder, use a conditional block with Greater/Less Than.

estimatedWait: Divides number of open work items by active agents, multiplied by average handling time. This value is in minutes.

In the dialogue builder, use a conditional block with Greater/Less Than.

These parameters are now available for use in the dialogue builder with an API node that calls the Agent Availability integration you built in the integration builder.