Zendesk Agent Availability Integration

Overview#

This integration lets CallGrid check how many of your Zendesk agents are online before it sends a call or bid to a destination. It runs on the destination's Ping and calls Zendesk's agent availabilities API. If no agent is online, the ping is rejected and routing moves to the next destination.

The ping runs for each call or bid that reaches the destination. It is not a background feed from Zendesk.

Prerequisites#

• Your Zendesk subdomain. If you sign in at yourcompany.zendesk.com, the subdomain is yourcompany.
• A Zendesk login the integration can use: the email address of a Zendesk agent or admin and an API token from Admin Center > Apps and integrations > APIs > Zendesk API.
• A CallGrid buyer and a destination for it, saved at least once (the Ping tab is available only after the destination is saved).

Step 1: Configure the destination Ping#

1. In CallGrid, go to Buyers > Destinations and edit the destination.
2. Open the Ping tab and turn on Ping Integration.
3. Turn on the Ping Template toggle, then in the template picker (Agent Availability group) choose Zendesk.
4. Fill in the template fields:
   • Username: the agent's email address followed by /token, for example jdoe@yourcompany.com/token.
   • Password: the Zendesk API token.
   • Subdomain: for example yourcompany.
5. Keep the Ping Timeout short so a slow Zendesk response does not delay routing.
6. Click Save Ping.

Turn on Ping Template (2), choose Zendesk (3) and fill in Password, Username and Subdomain (4).

The template sends a GET to https://<subdomain>.zendesk.com/api/v2/agent_availabilities with two headers: Authorization: Basic with your username and password encoded, and Zendesk-Api-Version: 2023-02-01. To see the request, turn Ping Template off: Request Data then shows what the template built.

Request Data built by the Zendesk template: the agent availabilities URL for your subdomain (2) and the two headers (3).

Zendesk is moving API access from API tokens to OAuth. If your Zendesk account gives you an OAuth access token instead, turn Ping Template off and change the Authorization header value to Bearer <your access token>.

Step 2: Set the acceptance rule#

The template counts online agents in Zendesk's response with Regex parsing:

• Parsing Type: Regex
• Regex type: Count, which counts matches of the pattern
• Pattern: "agent_status": {"name": "online"}

Then add the rule that decides acceptance: Property count, Greater Than, 0. That accepts when at least one agent is online.

Regex parsing (1) with Regex type Count (2) and the online-agent pattern (3), plus the rule count Greater Than 0 (4).

The count comes from the pattern, not from a property in the response, so leave Field Mapping > Agent Availability empty.

Step 3: Test#

1. In Ping Testing, click Run Ping.
2. Confirm the response lists your agents and that the accept or reject result matches your rule.
3. Test once with an agent online and once with every agent offline.
4. Click Save Ping, then Save Destination.

On the campaign Routing tab, place a fallback destination after the Zendesk destination and turn on Failover Routing. When the ping is rejected, routing continues to the next destination.

Step 4: Protect agents from overlapping calls#

Availability can change between the ping and the call, and two calls a few seconds apart can see the same free agent. In the destination's Capacity and Limit Settings, turn on Enable Capacity Guard and set Capacity Guard Seconds. Capacity Guard holds the destination out of new auctions for that time after its ping wins.

Failure handling and limits#

• Rejection Protection off: a Zendesk timeout or error rejects the ping and skips the destination. On: errors do not reject the call or bid. Turn it on only if you would rather send calls during a Zendesk outage than lose them.
• Every call or bid sends a request to Zendesk, and Zendesk applies its own API rate limits. Set Max Pings Per Minute on the destination to stay inside them. A rate-limited response counts as API Failed in Reports > Pings.

Monitoring#

Reports > Pings, grouped by destination, shows Accept %, Failed Accept (no agent online), Timeout %, API Failed and Avg ms for the Zendesk destination.

Troubleshooting#

Do it with AI#

Ask Claude or ChatGPT. Try: "How many pings to my Zendesk destination were accepted today, and how many were rejected because no agent was online?" Claude and ChatGPT need the CallGrid connector turned on (setup guides for Claude and ChatGPT).

The connector is read only. It looks things up and reads your data. You make the changes in CallGrid.

Stuck on a step? Ask Griddy.