Best practices

Authentication & Security

Always use HTTPS

Aircall webhooks require a valid SSL certificate. HTTP endpoints and self-signed certificates are not supported. You can use and support the Let's Encrypt project to get free SSL certificates.

Secure your credentials

• Store your API or OAuth credentials in environment variables, never in source code or version control.
• Use a dedicated API key per environment (dev / staging / prod).
• Rotate keys immediately if compromised.

Use the state parameter for OAuth apps

The state param is optional in Aircall's OAuth flow but you should always use it. It's your defense against Cross-Site Request Forgery (CSRF) — generate a random value, store it in the session, and verify it matches when Aircall redirects back to your redirect_uri.

See authentication guide →

Build for AI (MCP)

Design tool names for AI readability

When building an MCP server that exposes your system to AIVA, use clear, verb-noun tool names. The AI uses the name and description fields to decide which tool to call — ambiguity leads to wrong choices.

// Clear intent
{ name: "get_contact_recent_deals", description: "Fetch the 5 most recent deals" }
{ name: "create_support_ticket", description: "Open a new ticket in the helpdesk" }

// Too vague
{ name: "get_data", description: "Returns data" }

Keep tool inputs minimal and typed

Each additional required field is a chance for the AI to fail. Use defaults where possible and only require what's truly needed.

{
  name: "log_call_note",
  inputSchema: {
    type: "object",
    required: ["call_id", "note"],
    properties: {
      call_id: { type: "string" },
      note: { type: "string" },
      priority: { 
        type: "string",
        enum: ["low", "normal", "high"],
        default: "normal" 
      }
    }
  }
}

Target sub-200ms response times

AIVA calls MCP tools in real time, during or after a call. Slow tools degrade the agent experience. Aim for \< 200ms P95 latency by:

• Hosting your MCP server close to Aircall's infrastructure (Europe or US depending on your customer base)
• Using serverless edge functions (Cloudflare Workers, Vercel Edge) for low-latency reads
• Caching read-heavy lookups (contact data, deal status) with a short TTL

Separate read tools from write tools

Give AIVA read access broadly, but be explicit about which tools mutate data. This makes it easier to audit and control what the agent can do.

// Read tools - safe for AIVA to call freely
"get_contact_info", "search_deals", "get_ticket_status"

// Write tools - restrict to specific agent skills or confirm with user
"create_ticket", "update_deal_stage", "send_follow_up_email"

Webhooks

Prefer webhooks over polling

Real-time webhooks are more efficient, more reliable, and never hit rate limits. Avoid polling GET /v1/calls on a schedule unless you have a specific batch use case.

⚠️ Always return 200 immediately, Process webhooks asynchronously

Aircall waits for a 2XX response. If your server takes too long or returns an error, Aircall automatically disables the webhook after 50 consecutive failures.

Don't do heavy processing inline in your webhook handler. Push events to a queue (Redis, SQS, RabbitMQ) and process them separately or simply don’t use await and return a 2XX. This protects against timeouts and back-pressure.

Use the webhook token to identify accounts and source

When you create a webhook via the API, Aircall returns a token in the response. This token is included in every webhook payload — store it and use it to route events to the right account on your side.

During the OAuth install flow, once you've exchanged the code for an access_token, create your webhooks right away and make sure to pass your internal account ID when storing the webhook — that way the token is always linked to the right account record and you can look it up on every incoming event.

Subscribe only to what you need

Don't subscribe to all call events if you only need call.ended. Narrowing your subscription reduces noise and processing overhead.

Implement idempotency

Aircall can deliver the same webhook event more than once (network retries). Use the call.id as an idempotency key when writing to your database.

See Webhooks guide →

Rate limits & Pagination

Know the limits

Aircall's Public API is rate-limited to 120 requests per minute per API key or OAuth token. Exceeding this blocks your access for 60 seconds.

Implement exponential backoff on 429s

When you hit a 429, use the X-Aircallapi-Reset header to wait exactly until the window resets instead of guessing.

Use from and to to work with large datasets

The API caps results at 10,000 calls without the from parameter. Use from and to (Unix timestamp) to page through large volumes.