# Aircall Agent Availability Integration

> Let a CallGrid destination check whether any of your Aircall agents are available before it sends a call, using the Aircall ping template.

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

## Overview

This integration lets a CallGrid destination check whether any of your Aircall agents are available before it sends a call. The destination's **Ping** asks Aircall for your users' availability. If nobody is available, the ping is rejected and CallGrid routes the call elsewhere.

Where it lives: **Buyers > Destinations > Edit Destination > Ping tab**. It is a destination Ping, not an integration webhook.

## Prerequisites

- Aircall admin access.
- An Aircall **API ID** and **API Token**. In Aircall, open **Company Settings**, go to the **API Keys** section and click **Add a new API key**. Copy the token right away; Aircall does not show it again.
- A CallGrid destination that dials the Aircall number that rings those agents.

## Step 1: Create or open the destination

1. **Buyers > Destinations**, create or edit the Aircall destination. Set **Phone Type** to Phone with the Aircall number.
2. Set **Max Concurrent Calls** to the number of agents as a backstop, and consider **Capacity Guard** so one available agent is not sent overlapping calls.
3. Save. The Ping tab is available after the destination is saved.

## Step 2: Configure the Ping

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

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

1. Open the **Ping** tab and turn on **Ping Integration**.
2. Turn on **Ping Template** and select **Aircall**.
3. In **Basic Auth Token**, enter your API ID and API Token joined by a colon (`API_ID:API_TOKEN`) and Base64 encoded. Most terminals can produce it with `echo -n 'API_ID:API_TOKEN' | base64`.
4. Click **Save Ping**.

The template fills in the request for you:

| Setting | Value |
| --- | --- |
| Method | GET |
| URL | `https://api.aircall.io/v1/users/availabilities` |
| Header | `Authorization: Basic <your token>` |
| Acceptance Parsing | Regex, matching `"availability": "available"` |

The ping is accepted when at least one Aircall user in the response is available, and rejected when none are.

### Things to know

- **Aircall returns a status per user, not a count.** The ping answers "is anyone available?", so it cannot require three or five free agents, and **Field Mapping > Agent Availability** has no count to read. Use **Max Concurrent Calls** and **Capacity Guard** to limit volume.
- **Large teams.** Aircall returns users a page at a time (20 by default). If you have more than 20 users, add `?per_page=50` to the end of the URL so the check sees more of them.
- **Building it by hand.** Without the template, use the settings in the table above and put the Base64 value in a header, or use the macro `Authorization: Basic [[b64:YOUR_API_ID:YOUR_API_TOKEN]]`, which encodes the text for you.

## Step 3: Test

1. In **Ping Testing**, click **Run Ping**.
2. Read the raw Aircall response. With at least one agent set to available, the ping should be accepted; with everyone offline or busy, it should be rejected.
3. If the ping is rejected while an agent is available, compare the regex with the response text. It must match exactly, including spacing: if the response shows `"availability":"available"` with no space, change the regex to match.
4. Click **Save Ping**.

## Rate limits

Aircall allows 120 API requests per minute per company, and returns HTTP 429 when you go over. CallGrid pings the destination for each call or bid it considers, so busy campaigns can reach that limit, and other tools using the same Aircall account share it.

- Set **Max Pings Per Minute** on the destination below Aircall's limit, for example 100. It "applies on top of the buyer-level ping cap".
- A 429 from Aircall is counted under **API Failed** in Reports > Pings, together with genuine errors, which makes the failure rate look worse than it is.

## Monitoring

- **Reports > Pings** for the destination: Accepted, Failed Accept, Timeout, API Failed, Rate Ltd, Avg ms.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| Every ping fails with 401 | Token wrong or revoked; confirm it is the Base64 of `API_ID:API_TOKEN` |
| Every ping rejected even with agents available | Regex does not match the response text exactly; Run Ping and compare spacing |
| Rejected although an agent is free | The agent is beyond the first page of users; add `?per_page=50` to the URL |
| API Failed rising at peak | Aircall rate limit; lower Max Pings Per Minute |
| Ping rejected at all times | Agents not logged in, or set to Do Not Disturb in Aircall |
| Calls overlap on one agent | Enable Capacity Guard or lower Max Concurrent Calls |

## Do it with AI

**Ask Griddy, Claude or ChatGPT.** Try: "How many pings to my Aircall destination came back as API Failed 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.