Determining agent availability when escalating from AI agents

<div class="article-banners">
<div id="docs-wmp-link"><a href="https://support.zendesk.com/hc/en-us/articles/5411234991258-plan" rel="noopener noreferrer" target="_blank">What's my plan?</a></div>
<div class="article-banner" id="suite_all"><figure class="wysiwyg-table wysiwyg-table-align-left"><table><tbody><tr>
<td><strong>All Suites</strong></td>
<td>Team, Growth, Professional, Enterprise, or Enterprise Plus</td>
</tr></tbody></table></figure></div>
<div class="article-banner" id="support_all"><figure class="wysiwyg-table wysiwyg-table-align-left"><table><tbody><tr>
<td><strong>Support</strong></td>
<td>Team, Professional, or Enterprise</td>
</tr></tbody></table></figure></div>
</div><div class="body">

<div class="note attention">The availability check described in this article should be used only with CRM integrations other than Zendesk. To check Zendesk agent availability, see <a href="https://support.zendesk.com/hc/en-us/articles/8357749686554">Checking operating hours and agent availability during conversations with AI agents</a> instead.</div>
<p>When using an 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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>This article contains the following topics:</p>
<ul>
<li data-list-item-id="e515f0c9317bc4e3b734ef449f2b8aaf7"><a href="#h_01JMFX76J31ANNM16JVPP7MJ84">Prerequisites for setting up the Agent Availability API in the integration builder</a></li>
<li data-list-item-id="ef38ca6ec44d74375d6a123f692773134"><a href="#h_01JMFX7FHJVSD81JJFWDP3AT12">Creating a token to access the API</a></li>
<li data-list-item-id="eb25027af57a80e5a17a2f7d170e5e639"><a href="#h_01JMFX8KN5FJX16RDYDT6CW8V0">Creating the integration in the integration builder</a></li>
</ul>
<h2 id="h_01JMFX76J31ANNM16JVPP7MJ84">Prerequisites for setting up the Agent Availability API in the integration builder</h2>
<p>To set up the Agent Availability API in the integration builder, you'll need to gather the following key information:</p>
<ul>
<li data-list-item-id="e9c7611d078a306d2c66f61a426040407">
<strong>The Zendesk subdomain.</strong> 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.</li>
<li data-list-item-id="efe1087dd464220c106bb5340debb029f">
<strong>Auth token and an admin email.</strong> Created in Admin Center, this token will authorize your AI agent to make the request for the Agent Availability data.</li>
<li data-list-item-id="e7f903aac1aa68d354437f554a9ed3a50">
<strong>Any group ID (if applicable).</strong> If you want to filter for online agents belonging to a specific group, you can do so with a URL query.</li>
</ul>
<h2 id="h_01JMFX7FHJVSD81JJFWDP3AT12">Creating a token to access the API </h2>
<p>To access the Zendesk API, you'll need to create a token in Admin Center.</p>
<p><strong>To create an API token</strong></p>
<ol>
<li data-list-item-id="e6fa27a1916c7f175148e76f9f1a370c3">In <a href="https://support.zendesk.com/hc/en-us/articles/4581766374554#topic_hfg_dyz_1hb">Admin Center</a>, click <strong>Apps and integrations</strong> in the sidebar, then select <strong>APIs</strong> &gt; <strong>Zendesk API</strong>.</li>
<li data-list-item-id="e28547920fe8fbc72b6fa92ab43647e71">Click <strong>Add API token</strong>.<br><img src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/aiaa_agent_avail_1.png" width="600">
</li>
<li data-list-item-id="e1b4ed8be4ddd27c6e263e79fbb865205">Give the token a descriptive name, such as <strong>Agent Availability</strong>.</li>
<li data-list-item-id="e593f6109c6573e7c517b61664fb877e4">Copy the token somewhere safe, as you'll need this for setting up the integration in the integration builder.</li>
</ol>
<h2 id="h_01JMFX8KN5FJX16RDYDT6CW8V0">Creating the integration in the integration builder</h2>
<ol>
<li data-list-item-id="e731152e870fe9fba12ba9a471ccea318">Create an integration in the integration builder.</li>
<li data-list-item-id="e702d941fc3c5edd4051b86f534ff75cd">Go to the <strong>Environment</strong> tab and select your chosen environment (for example, Production, or you could change this to something more descriptive such as getAgents).</li>
<li data-list-item-id="e01869b7b4b078e776faf854db6eaae86">Set up the endpoint using the following format, replacing <em>[your-subdomain]</em> with your subdomain:<br><em>https://[your-subdomain].zendesk.com/api/v2/agent_availabilities</em>
</li>
<li data-list-item-id="e9fdff37a0a137a9305ed3f0b39fe2a98">(Optional) Further customize the query URL by filtering.<ul>
<li data-list-item-id="ed3be88e2862a4b65c7234dee64961494">Example 1: If you want to check how many agents are online now in the messaging channel:<br><em>https://[your-subdomain].zendesk.com/api/v2/agent_availabilities?filter[channel_status]=messaging:online</em>
</li>
<li data-list-item-id="e672ee13759819ee5c54b8f7bc9c540e9">If you want to check for agents available online and in a specific service group:<br><em>https://[your-subdomain].zendesk.com/api/v2/agent_availabilities?filter[channel_status]=messaging:online&amp;filter[group_id]={{groupId}}</em><br>For more information, see <a href="https://developer.zendesk.com/api-reference/agent-availability/agent-availability-api/introduction/">Agent Availability API</a>.</li>
</ul>
</li>
<li data-list-item-id="e757c2c9d0521fbd0798912336474f90a">On the <strong>Authorization</strong> tab, set the <strong>Authorization type</strong> to <strong>Basic Auth</strong>.<ul>
<li data-list-item-id="ea0220cffffb09a14104734c32216e301">
<strong>Username</strong>: Your admin email address with ‘/token’ appended (for example, admin@yourcompany.com/token).</li>
<li data-list-item-id="ed380a7c5b1195d17a8e82f18479a4818">
<strong>Password</strong>: Paste the API key you generated earlier in Admin Center.</li>
</ul>
</li>
<li data-list-item-id="e75f45ae3f49a31cf06101f91bb9cf1a7">On the <strong>Headers</strong> tab, click <strong>Add Header. </strong>
</li>
<li data-list-item-id="e676e2905a9a253abc74b11a701fc9ca2">In the <strong>Key</strong> field, enter <strong>Authorization</strong>. </li>
<li data-list-item-id="e4c8bf73fa25f123d8ca2c1c1b05c46c9">In the <strong>Value</strong> field, enter <strong>Basic {{apiToken}}</strong>.<br><img src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/aiaa_agent_avail_2.png" width="600">
</li>
<li data-list-item-id="e3a59ec2cd630cd7129ab323a52fa08fd">(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 <strong>Request parameters</strong> with a key such as <strong>groupId</strong> and adding <strong>&amp;filter[group_id]={{groupId}}</strong> to the URL (as demonstrated in step 4).<br><img src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/aiaa_agent_avail_3.png" width="600">
</li>
</ol>
<p>With that all set up, you should be able to successfully test your integration to view the response.</p>
<p><img src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/aiaa_agent_avail_4.png" width="600"></p>
<p>For the success scenario, you can now add your session parameters. Here are three commonly useful example parameters:</p>
<ul>
<li data-list-item-id="eebb7fcfea0016fbeacc65d29730e7bca">
<strong>agentCheck</strong>: Provides an array of relevant available agents.<ul><li data-list-item-id="e638656dcc2c99c8f625defe1ba479659">In the dialogue builder, use a conditional block with Includes.</li></ul>
</li>
<li data-list-item-id="ed3ea09275b1e7b1ca018ff4c40c9f102">
<strong>availableAgent</strong>: Provides number of relevant available agents.<ul><li data-list-item-id="e003c0ad56c6d1cd19c4534f11573e73a">In the dialogue builder, use a conditional block with Greater/Less Than.</li></ul>
</li>
<li data-list-item-id="ecbd8f02fb3c41b477ce1ab91ab7efc91">
<strong>estimatedWait</strong>: Divides number of open work items by active agents, multiplied by average handling time. This value is in minutes.<ul><li data-list-item-id="e3d00fd158a5a3104a63f0d141122e4b4">In the dialogue builder, use a conditional block with Greater/Less Than.<br><img src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/aiaa_agent_avail_5.png" width="600">
</li></ul>
</li>
</ul>
<p>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.</p>
<p> </p>
<script id="docs-schema-markup" type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "TechArticle",
"@id": "https://support.zendesk.com/hc/en-us/articles/8920466700698",
"url": "https://support.zendesk.com/hc/en-us/articles/8920466700698-Determining-agent-availability-when-escalating-from-advanced-AI-agents",
"headline": "Determining agent availability when escalating from advanced AI agents",
"description": "You can set up an API integration to check the availability of specific agents or groups for escalating conversations from advanced AI agents, using detailed status and workload data to improve handoffs and routing in customer support.",
"articleSection": "Integrating other platforms with advanced AI agents",
"datePublished": "2025-02-19T20:09:56+00:00",
"dateModified": "2025-10-22T12:45:34+00:00",
"inLanguage": "en-US",
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://support.zendesk.com/hc/en-us/articles/8920466700698"
},
"author": {
"@type": "Organization",
"name": "Zendesk",
"@id": "https://www.zendesk.com"
},
"publisher": {
"@type": "Organization",
"name": "Zendesk",
"@id": "https://www.zendesk.com"
},
"isPartOf": {
"@type": "WebSite",
"name": "Zendesk Help",
"@id": "https://support.zendesk.com/hc/"
},
"about": {
"@type": "SoftwareApplication",
"name": "Zendesk",
"@id": "https://www.zendesk.com",
"softwareAddOn": {
"@type": "SoftwareApplication",
"name": "AI agents",
"@id": "https://support.zendesk.com/hc/en-us/sections/8988994355994"
}
}
}
</script>
</div>