> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Aircall troubleshooting

> Debug Aircall workflow errors: call not found after transfer, rejected credentials, comment limits, and oversized insight cards.

Before debugging, have this ready:

* The **workflow run ID** from your [OpenCX dashboard](https://platform.open.cx) (run viewer → failed run).
* The **caller's phone number** for the failed transfer.
* Whether the call actually shows up in Aircall's own call history.

<Tip>
  The workflow run viewer shows each node's input and output. Most Aircall failures surface there as a descriptive error on the action — read it before assuming the integration is down.
</Tip>

## Common scenarios

### **"No recent Aircall call found for phone number …"**

<Tooltip tip="OpenCX finds the transferred call in Aircall by looking up the caller's phone number, retrying for up to Max Wait seconds.">Likely cause</Tooltip>: OpenCX couldn't find the transferred call under the caller's number.

**Fix:**

* Make sure **Caller Phone Number** is set to `{{trigger.ticket.contact.phone_number}}` — the customer's number, not your Aircall number.
* If new calls take a while to appear in Aircall, raise **Max Wait (seconds)** so OpenCX keeps looking a bit longer.
* Open the call in Aircall's call history. If the caller shows as **anonymous** or an unknown number, [contact us](#none-of-the-above) — that's something we need to fix on our side.

### **Action fails with "Aircall rejected the credentials (401/403)"**

<Tooltip tip="Aircall answers invalid or revoked API key pairs with 403 Forbidden (sometimes 401). The action maps both to a credentials error.">Likely cause</Tooltip>: a typo in the API ID/token, or the key was revoked.

**Fix:** re-run the ping check from [Connect](/integrations/aircall/connect#verify-the-connection). If it fails, generate a fresh key from the [Aircall API Keys page](https://dashboard.aircall.io/view-api-keys) and update the workflow node.

### **The comment fails to post**

<Tooltip tip="Aircall allows a maximum of five comments per call and rejects any comment after that. Comments also cannot be edited or deleted once posted.">Likely cause</Tooltip>: the call already has 5 comments — Aircall's maximum — for example, because the workflow fired more than once for the same transfer.

**Fix:** keep one context-posting workflow per transfer path. If you need multiple pieces of context, combine them into a single comment instead of posting several.

### **"Insight card payload exceeds the 10KB limit"**

<Tooltip tip="Aircall limits how much content an insight card can hold. OpenCX checks the size before posting and fails with this message instead of sending a card Aircall would reject.">Likely cause</Tooltip>: one of the card's fields contains a very large value — typically a full transcript.

**Fix:** put summaries on the card, not transcripts. If the agent needs more detail, add a field with a **Link** to the OpenCX session and keep the card text short. Long context belongs in the call comment.

### **The card never shows up in the agent's phone app**

<Tooltip tip="Insight cards are only displayed on ongoing calls and are discarded the moment the call ends. A card posted after hangup is accepted by the API but never rendered.">Likely cause</Tooltip>: the card was posted after the call ended (e.g. a very short call, or a long **Max Wait**).

**Fix:** treat the card as best-effort garnish and keep the comment as the durable record. Shorter comment content and a low **Max Wait** get the card up faster.

### **None of the above**

Send your OpenCX contact the failing **workflow run ID** and the **caller phone number** (redact the API token from any screenshots). We'll trace from there.

## Limits & timing

|                              | Value                                                                |
| ---------------------------- | -------------------------------------------------------------------- |
| **Per-request HTTP timeout** | 30 seconds for each Aircall API call                                 |
| **Call lookup budget**       | **Max Wait (seconds)** input, default 30s, max 40s, polling every 3s |
| **Search window**            | Calls created in the last 15 minutes                                 |
| **Comments per call**        | 5 (Aircall limit; comments are immutable)                            |
| **Insight card payload**     | 10KB max (Aircall limit)                                             |

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Connect" icon="plug" href="/integrations/aircall/connect">
    Re-verify the API ID and token.
  </Card>

  <Card title="Post Call Context Action" icon="phone-forwarded" href="/integrations/aircall/post-call-context-action">
    Inputs, matching rules, and output reference.
  </Card>

  <Card title="Overview" icon="phone" href="/integrations/aircall/overview">
    How the transfer + context flow fits together.
  </Card>

  <Card title="AI Phone agent configuration" icon="gear" href="/phone/agent-config">
    Transfer destinations on the phone agent.
  </Card>
</CardGroup>