# Genesys Cloud Agent Availability Integration

> How to make a CallGrid destination check a Genesys Cloud queue for available agents before each call or bid, so calls only go out when agents are ready.

Source: https://callgrid.com/knowledge-base/genesys-cloud-agent-availability-integration
Last updated: 2026-10-28
Topics: Integrations, Agent Availability

## 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

![Destination Ping tab with the Genesys Cloud template selected](https://callgrid.com/api/media/file/kb-Genesys-template.png)

![Genesys Cloud ping request data and headers](https://callgrid.com/api/media/file/kb-Genesys-request.png)

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

| Acceptance rule | Meaning |
| --- | --- |
| `total` Greater Than `0` | At least 1 available agent |
| `total` Greater Than `2` | At least 3 available agents |
| `total` Greater Than `4` | At least 5 available agents, for busy periods or long-hold buyers |

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

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| Pings worked, then all fail with 401 | The pasted bearer token expired | Set up Authorization so CallGrid fetches tokens; Token Path `access_token` |
| Every ping fails with 401 | Token request failing | Check the Client ID and Client Secret in the Basic header and the login host for your region |
| 403 | OAuth role cannot view queue members | Add queue member view permission to the client's role |
| 404 | Wrong Queue ID or region host | Recheck the ID and API domain |
| `total` always 0 | Agents not joined to the queue or not in Available presence | Check agents in Genesys; the query filters `presence=Available&joined=true` |
| High Timeout % | Genesys slow or Timeout too low | Raise Timeout slightly; a per-source **Webhook Timeout** override on the campaign Sources tab sets the destination ping timeout for that source |
| High API Failed | Rate limited (429) or Genesys errors | Lower Max Pings Per Minute, enable Ping Guard |
| Calls still arrive when agents are busy | Availability changed between ping and call, or bids won before the check | Raise the threshold, enable Capacity Guard, set concurrency caps |

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

```bash
curl -X POST "https://login.mypurecloud.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d "grant_type=client_credentials"

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  "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](https://callgrid.com/knowledge-base/callgrid-mcp-connect-to-claude-desktop) and [ChatGPT](https://callgrid.com/knowledge-base/callgrid-mcp-connect-to-chatgpt)).

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