AI-powered outbound calls

Use the AIVA API to place outbound calls to contacts on behalf of your company — triggered from your CRM, scheduling tool, or any automation platform.

You send a phone number, an agent ID, and any context variables the agent needs to personalize the conversation. AIVA handles: dialling the contact, running the conversation, and logging the outcome.

What can you build

Because the trigger is a simple POST request, it slots into almost any system that can make an HTTP call — a CRM, a workflow automation tool, a back-end job queue, or a Zapier trigger. Here are a few ideas:

The Request

The body takes a contact_phone number, a uniqueidempotency_key to prevent duplicate calls, and an optional context object.

Context is key-value pairs that fill in {{variable}} placeholders in the agent's first message — so the agent can say "Hi Jane, calling about your appointment on April 23rd" rather than a generic greeting.

Every placeholder used in the message must have a matching key in context, otherwise the call is rejected. You can find the agent_id in the agent's configuration page in the Dashboard.

const agentId = "AGENT_ID";
const token = "YOUR_TOKEN";

const payload = {
  contact_phone: "+15551234567",
  idempotency_key: "appt-reminder-2026-04-22-cust-9981",
  context: {
    first_name: "Jane",
    appointment_date: "April 23rd at 2:00 PM",
  },
  expiration_seconds: 3600,
};

async function createOutboundCall() {
  try {
    const response = await fetch(
      `https://api.aircall.io/v1/outbound-calls/agents/${agentId}`,
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${token}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify(payload),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      throw new Error(data.message || "Failed to create outbound call");
    }

    console.log("Outbound call created:", data);
  } catch (error) {
    console.error("Request error:", error.message);
  }
}

createOutboundCall();

curl -X POST https://api.aircall.io/v1/outbound-calls/agents/AGENT_ID \ 
   -H "Authorization: Bearer YOUR_TOKEN" \ 
   -H "Content-Type: application/json" \ 
   -d '{ 
      "contact_phone":   "+15551234567", 
      "idempotency_key": "appt-reminder-2026-04-22-cust-9981", 
      "context": { 
         "first_name":       "Jane", 
         "appointment_date": "April 23rd at 2:00 PM" 
      }, 
      "expiration_seconds": 3600 
      }'

A few things to note:

• Successful request returns 202 Accepted
• The call is queued, not yet placed.
• If the concurrency limit is reached, the system keeps retrying until expiration_seconds elapses (default 1 hour).
• Calls and their outcomes are logged in the Conversation Center like any other call.
• See the API reference for the full parameter list, response shape, and error codes.

Automating outbound calling in your product

If you're building a product integration — for campaigns, outbound flows, or any automated calling feature — the recommended pattern is to let each customer bring their own agent. Your product triggers it; the customer owns and configures the conversation. This keeps your integration lightweight and fully customizable for each user.

1. Ask the user to create an Outbound Voice Agent in Aircall
   Direct them to Dashboard → AI Voice Agents. They configure the script, tone, first message, and any transfer rules. You don't own any of this — they do.

2. Optionally, guide them on what to set up
   If your use case benefits from a specific configuration — particular intake questions, custom API actions connected to their own systems — surface those recommendations in your UI. This is especially useful until MCP integrations enable agent actions for partner products.
3. Let the user connect their agent to your product
   Once the Aircall connection is authorized, show a settings screen where the user pastes their Agent ID and defines the context variables your product will send at runtime — either as a JSON object or a structured key-value form.

4. Trigger by agent ID and context at runtime
   When an event fires in your product — a campaign starts, a record reaches a certain stage, a trigger condition is met — call the endpoint with the saved agent ID and populate the context from your own data. The customer's agent handles the conversation.

This scales cleanly: each customer configures their own agent exactly as they need, and your integration stays consistent across all of them. You're not hard-coding any conversation logic — customers own it and can iterate on it independently, without touching your product.

// User configures once in your integration settings:
Agent ID        "01JPAE0N1FFTC5D8G4K5PZMDGG
"Context schema  { 
   "first_name": "{{contact.first_name}}", 
   "renewal_date": "{{account.renewal_date}}" 
}  

// Your backend resolves the template and fires at runtime: 
POST /v1/outbound-calls/agents/01JPAE0N1FFTC5D8G4K5PZMDGG 
{ 
   "contact_phone":   "+15551234567", 
   "idempotency_key": "renewal-2026-04-22-acct-7741", 
   "context": { 
      "first_name":    "Jane", 
      "renewal_date": "May 1st" 
   } 
}