Genesys Cloud Agent Availability Integration

What this article covers#

How to make a CallGrid destination check a Genesys Cloud queue for available agents before each call or bid, so calls only go to the buyer when agents are ready. The check is the destination's Ping: a request CallGrid sends to Genesys Cloud, whose response decides whether the destination is considered for that call.

Prerequisites#

• A Genesys Cloud organization and an admin who can create OAuth clients.
• The Queue ID of the queue to monitor.
• Your Genesys Cloud region's API and login hosts. The examples below use api.mypurecloud.com and login.mypurecloud.com (US East). Other regions use different domains, so confirm yours in Genesys.
• A CallGrid destination (Buyers > Destinations) for this buyer, saved at least once. The Ping tab is enabled only after the destination is saved.

Step 1: Create the OAuth client in Genesys Cloud#

1. In Genesys Cloud, click Menu > IT and Integrations > OAuth, then Add client.
2. Grant type: Client Credentials.
3. Assign a role that can view routing queue members.
4. Save and copy the Client ID and Client Secret. Genesys shows the secret only once.

Step 2: Find the Queue ID#

1. In Genesys Cloud Admin, open Contact Center > Queues.
2. Open the queue and copy its ID (a UUID such as 12345678-1234-1234-1234-123456789abc).

Step 3: Build the destination Ping in CallGrid#

1. Open Buyers > Destinations, edit the destination and select the Ping tab. Turn on Ping Integration.
2. Turn on Ping Template and select Genesys. Enter your Queue ID. The template also asks for a Bearer Authentication Token; you can paste a token here to test, but Genesys tokens expire, so set up Authorization in the next step to keep the ping working.
3. Check what the template filled in under Request Data:
   • Method: GET
   • URL: https://api.mypurecloud.com/api/v2/routing/queues/<QUEUE_ID>/members?expand=presence&presence=Available&joined=true
   • If your Genesys region is not US East, change api.mypurecloud.com to your region's API host.
   • Timeout: seconds CallGrid waits for Genesys. Keep it short; a slow response delays routing.
4. Authorization (so CallGrid fetches and refreshes the token for you):
   • Turn on Authorization. It "authenticate[s] against an endpoint to get an access token before sending the main ping request. The access token is injected into the main request headers."
   • Method POST, URL https://login.mypurecloud.com/oauth/token (or your region's login host).
   • Content Type Form Encoded, body grant_type=client_credentials.
   • Add an Auth Headers entry Authorization: Basic [[b64:CLIENT_ID:CLIENT_SECRET]] with your Client ID and Client Secret. The macro Base64 encodes the text for you.
   • Token Path: access_token.
   • Header Name: Authorization. Header Prefix: Bearer.
   • Token TTL (sec): how long CallGrid caches the token, minimum 60, maximum 86400. Set it below the token lifetime Genesys issues.
   • Remove the static Authorization: Bearer header the template added, so the fetched token is the one sent.
5. Acceptance Parsing (set by the template):
   • Parsing Type JSON.
   • Key total, operator Greater Than, value 0.
   • An accepted ping makes the destination eligible for that call or bid; a rejected ping leaves it out.
6. Optional: Field Mapping > Agent Availability, map total to record the number of available agents with each ping (the Avg Agents column in Reports > Pings and the Agents report).
7. Click Run Ping. Check that the response includes total and that the acceptance result matches what you see in Genesys.
8. Click Save Ping.

Choosing a threshold#

Use a higher threshold when several campaigns or publishers share the same queue, since the ping reflects availability at that moment, not agents reserved for CallGrid.

How it behaves on live traffic#

• CallGrid sends the ping when the destination is being considered for a call or a bid.
• Turbo Routing can cancel this ping when a higher-priority destination has already won.
• Ping Guard (bidding campaigns) reuses one ping per caller across duplicate bidders during the bid expiration window, which reduces calls to the Genesys API.
• Capacity Guard on the destination holds it out of new auctions for a set number of seconds after it wins, so a single available agent is not offered overlapping calls.
• Pair availability with Max Concurrent Calls or Hard Concurrency Cap as a backstop.

Rate limits#

Genesys Cloud enforces API rate limits per OAuth client. To stay under them:

• Set Max Pings Per Minute on the destination (0 means unlimited). It "applies on top of the buyer-level ping cap."
• Enable Ping Guard on bidding campaigns.
• Use one OAuth client per integration so other tools do not share its limit.

A 429 returned by Genesys is counted under API Failed in the Pings report together with genuine errors, which inflates the failure rate. Check the ping detail's Code before assuming Genesys is down.

Monitoring#

• Reports > Pings, grouped by DestinationName: Accepted, Failed Accept, Timeout, API Failed, Rate Ltd, Accept %, Avg ms, Avg Agents.
• Reports > Agents: Destination, Buyer, Agents Available. It shows the last ping within the last five minutes, so a queue with no recent pings shows no agents.
• Pings detail log: Ping ms, Agents, Code per ping.

Troubleshooting#

Consider Rejection Protection ("Do not reject the call or bid if the webhook http status code is not 200") only if you would rather send calls during a Genesys outage than lose them.

Manual API test#

1curl -X POST "https://login.mypurecloud.com/oauth/token" \2  -H "Content-Type: application/x-www-form-urlencoded" \3  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \4  -d "grant_type=client_credentials"5
6curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \7  "https://api.mypurecloud.com/api/v2/routing/queues/YOUR_QUEUE_ID/members?expand=presence&presence=Available&joined=true"

Genesys resources#

• Genesys Cloud Developer Center: https://developer.genesys.cloud/ (Platform API, OAuth client credentials and Routing API reference)

Do it with AI#

Ask Griddy, Claude or ChatGPT. Try: "What is the Timeout % on pings to my Genesys Cloud destination this week?" 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.