Aircall Agent Availability Integration

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#

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:

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#

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 and ChatGPT).

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