Trigger an AI call from your CRM

A deal moves to Qualified, or a renewal falls due, and someone should phone the customer. This recipe has your agent make that call — placed from your CRM's automation, with the outcome written back onto the record without anyone listening to a recording.

The call itself is asynchronous and that shapes the whole design. POST /calls returns as soon as the number rings. Everything you care about — whether they answered, how long they talked, what happened — arrives afterwards.

What you need before you start #

• A phone number with an agent deployed to it. Numbers are requested and KYC-verified in the console; the answering agent is set by activating a deployment on that number. See Numbers and KYC and Deployments.
• An API key with calls:write. The same scope covers placing, reading, and hanging up. Tick Place calls under What this key can do when you create the key; scopes can't be added to a key later.
• A webhook endpoint subscribed to call.ended and call.outcome. call.ended tells you how the line ended; call.outcome tells you what the call achieved and brings back your own metadata. call.started is optional and useful for live dashboards.

The sequence #

1. Your CRM automation fires on a stage change and enqueues a job.
2. The job checks your own guards — do not call, quiet hours, already called today — then POSTs to /calls.
3. 201 comes back with status: "ringing" and a call_id. Store it on the CRM record.
4. If the call connects, call.started fires, and the agent opens the conversation, states who it is calling for, and asks whether now is a good time.
5. call.ended fires with the line outcome and duration. Your handler maps it to a dial disposition.
6. Usually within a minute, call.outcome fires with the reading — disposition, summary, answers — and your metadata. Your handler writes the result back to the record.

Choosing the caller-ID number #

from_number is the number the customer sees, and it does more than that: the agent that speaks is resolved from the caller-ID number, not from agent_id.

That is the single most surprising thing about this endpoint, and it follows from how the platform works — an agent is bound to a number by activating a deployment, so the number already answers the question of who is calling. Passing agent_id does not choose an agent; it asserts which one you expect, and fails loudly if you are wrong:

{
  "error": {
    "code": "failed_precondition",
    "message": "The agent deployed to this number is different from the one requested.",
    "details": {
      "reason": "agent_number_mismatch",
      "deployed_agent_id": "bot_01JQRS4T8XZ0AB1CD2EF3GH4"
    },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}

Send agent_id anyway. It converts "we silently called 400 customers with the renewals agent instead of the onboarding one" into a 412 on the first call.

The rules:

• from_number must be an active number owned by your workspace, matched on digits. A number belonging to another workspace is a 403.
• Omit it and the first active number is used. That is fine for a workspace with one number and a latent bug for a workspace that adds a second.
• Your numbers are listed in the console under Channels → Phone / Voice. Pin the one you want in configuration rather than discovering it at call time.
• The destination cannot be one of your own numbers — that returns 400 with self_dial.

Telling the agent why it is calling #

purpose is up to 500 characters and it is not a label. It reaches the agent's opening line and its instructions for the whole call, so it is the difference between an agent that knows why it phoned and one that improvises.

Write it as a brief to a colleague, with the facts the agent will need:

{
  "to": "+919876543210",
  "from_number": "+912269850800",
  "agent_id": "bot_01JQRS4T8XZ0AB1CD2EF3GH4",
  "purpose": "Rohit's annual maintenance plan for AC unit AM-4821 renews on 15 August at ₹4,500. Confirm whether he wants to renew, and if he does, tell him a payment link follows on WhatsApp. If he wants to cancel, ask why and thank him.",
  "ring_seconds": 30,
  "metadata": { "crm_record_id": "opp_88213", "owner": "priya@acme.in" }
}

Good purposes name the customer's situation, the specific outcome you want, and what to do in the obvious branches. Bad ones — "renewal call" — leave the agent to guess, and it will.

The opening line is fixed by us, not generated from purpose: the agent identifies the business, discloses that it is a virtual assistant, and asks whether now is a good time — in that order, before anything else happens. You cannot replace that with a sales opener, and it is deliberate.

metadata is free-form, stored on the call, and never spoken. It comes back, unchanged, on the call.outcome webhook — put your CRM record id there. It is not on call.ended, which carries only the call_id, so store the call_id from the 201 as well.

Placing the call #

// place-call.js
const BASE_URL = "https://services.amomic.in/api/v1";
const API_KEY = process.env.AMOMIC_API_KEY;
const CALLER_ID = process.env.AMOMIC_CALLER_ID;   // "+912269850800"
const AGENT_ID = process.env.AMOMIC_AGENT_ID;     // asserts the deployed agent

// An error response releases the Idempotency-Key, so a requeue after one
// reuses the same key and runs fresh.
async function placeRenewalCall(opportunity) {
  // Your compliance guards run here, before anything is dialled.
  if (opportunity.doNotCall) return { skipped: "do_not_call" };
  if (!withinCallingHours()) return { skipped: "outside_hours" };

  const body = JSON.stringify({
    to: opportunity.contactPhone,       // "+919876543210" — digits, optional +, nothing else
    from_number: CALLER_ID,
    agent_id: AGENT_ID,
    purpose: renewalBrief(opportunity),
    ring_seconds: 30,                   // 10-90
    metadata: { crm_record_id: opportunity.id },
  });

  const response = await fetch(`${BASE_URL}/calls`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
      // Derived from the CRM event. A network retry or a requeue reuses this
      // exact key.
      "Idempotency-Key": `renewal-${opportunity.id}-${opportunity.stageChangedAt}`,
      "X-Correlation-Id": opportunity.traceId,
    },
    body,
  });

  if (response.ok) {
    const call = await response.json();
    // status is "ringing". Nobody has answered anything yet.
    await crm.update(opportunity.id, { amomicCallId: call.call_id, callState: "ringing" });
    return call;
  }

  const { error } = await response.json();
  const reason = error.details?.reason;

  if (reason === "rate_limited") {
    // 120 requests/minute on this key. Refused before the key was claimed.
    await queue.retryIn(opportunity.id, 60_000);
    return { deferred: true };
  }

  if (reason === "call_concurrency" || reason === "originate_failed") {
    // All 10 outbound slots are busy, or the call could not be placed.
    // Requeue; do not spin.
    await queue.retryIn(opportunity.id, 60_000);
    return { deferred: true };
  }

  if (reason === "daily_call_budget") {
    // The workspace's daily outbound limit. Try again tomorrow (UTC).
    await queue.retryTomorrow(opportunity.id);
    return { deferred: true };
  }

  // Everything else is a configuration or data problem. Surface it.
  await crm.update(opportunity.id, { callState: "failed", callError: reason ?? error.code });
  throw new Error(`${error.code}/${reason ?? "-"}: ${error.message} (${error.request_id})`);
}

{
  "call_id": "call_01JQRS4T8XZ0AB1CD2EF3GH4",
  "status": "ringing",
  "direction": "outbound",
  "to": "+919876543210",
  "from_number": "+912269850800",
  "agent_id": "bot_01JQRS4T8XZ0AB1CD2EF3GH4",
  "duration_seconds": null,
  "outcome": null,
  "summary": null,
  "recording_uri": null,
  "started_at": null,
  "ended_at": null,
  "capture": null,
  "result": {
    "state": "pending",
    "disposition": null,
    "goal_met": null,
    "success": null,
    "summary": null,
    "sentiment": null,
    "next_step": null,
    "next_step_reason": null,
    "fields": {},
    "captured": 0,
    "expected": 0,
    "missing_required": [],
    "read_at": null
  }
}

Errors worth handling by name #

Only three of those are worth an automatic retry: call_concurrency and originate_failed in a minute, and daily_call_budget tomorrow. All three come back after the Idempotency-Key was claimed, and an error response releases it, so the requeued call reuses the same key and runs fresh. The rest are configuration or billing, and a retry loop against them just burns your rate limit. Calls lists every refusal and Errors every reason.

The concurrency limit #

Ten outbound calls per workspace at once. The eleventh returns 429 with details.reason of call_concurrency and details.limit of 10. This is separate from the 120-requests-per-minute key limit and is not affected by it.

For a CRM trigger firing a handful of calls a day, you will never see it. For a batch — 200 renewals on the first of the month — you must pace, because the limit counts live calls, not requests, and a three-minute conversation holds its slot for three minutes.

The shape that works:

• Keep a worker pool of at most 8 or 9 concurrent calls, leaving headroom for anything else in the workspace that dials.
• Release a slot when call.ended arrives, not when the 201 does.
• On call_concurrency, requeue with a delay of about a minute. Do not retry immediately; the slot is busy for as long as the conversation lasts.

Waiting for the outcome #

Subscribe to call.ended for how the line ended — answered or not, and for how long — and to call.outcome for what the call achieved (below).

{
  "id": "evt_7b1e9a3c5d2f8e6a0c4b7d92",
  "type": "call.ended",
  "created_at": "2026-08-01T11:07:31Z",
  "tenant_id": "ten_01JQRS4T8XZ0AB1CD2EF3GH4",
  "data": {
    "call_id": "call_01JQRS4T8XZ0AB1CD2EF3GH4",
    "duration_seconds": 96,
    "outcome": "caller_hangup",
    "direction": "outbound",
    "to": "+919876543210",
    "event_id": "evt_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}

Fields with no value are omitted rather than sent as null, so read with defaults. Delivery is at-least-once — deduplicate on the envelope id.

The reconciliation sweep:

// reconcile-stuck-calls.js — run on a 15-minute schedule
async function reconcileStuckCalls() {
  // Ringing far longer than any real call could be: your ring_seconds plus
  // the maximum call length configured on the number.
  const stale = await crm.findCalls({ state: "ringing", olderThanMinutes: 20 });

  for (const record of stale) {
    const response = await fetch(`${BASE_URL}/calls/${record.amomicCallId}`, {
      headers: { Authorization: `Bearer ${API_KEY}` },
    });

    if (response.status === 404) {
      await crm.update(record.id, { callState: "unknown" });
      continue;
    }
    if (!response.ok) continue;   // try again next sweep

    const call = await response.json();
    if (call.status === "ringing" || call.status === "in_progress") continue;

    await applyDisposition(record, call);
    await sleep(600);             // stay well inside 120 requests/minute
  }
}

Mapping outcomes to dispositions #

Two fields describe how a call finished. status is the coarse lifecycle state; outcome is the one to map, because it distinguishes a busy signal from a rejection from a conversation that ended normally.

An important detail: a call that was never answered still finalises with status: "completed" and duration_seconds: 0. Branching on status alone will book every voicemail as a conversation. Branch on outcome, and use duration_seconds to sanity-check it.

The call never connected:

The call connected and a conversation happened:

Something went wrong on our side:

A handler that puts it together:

const NEVER_CONNECTED = {
  no_answer: "No answer",
  busy: "Busy",
  rejected: "Rejected",
  invalid_number: "Bad number",
  unreachable: "Unreachable",
  congestion: "Retry",
};

const CONNECTED = {
  caller_hangup: "Contacted",
  agent_hangup: "Contacted",
  idle: "Contacted, no engagement",
  max_duration: "Contacted, truncated",
};

const PLATFORM_FAILURE = {
  originate_error: "Failed",
  setup_error: "Failed",
  suspended: "Blocked",
};

function disposition(call) {
  const outcome = call.outcome ?? "";
  if (outcome in PLATFORM_FAILURE) return PLATFORM_FAILURE[outcome];
  if (outcome in NEVER_CONNECTED) return NEVER_CONNECTED[outcome];
  if (outcome in CONNECTED) return CONNECTED[outcome];
  console.warn("unmapped call outcome", { outcome, call_id: call.call_id });
  return "Unknown";
}

async function onCallEnded(data) {
  const record = await crm.findByCallId(data.call_id);
  if (!record) return;

  await crm.update(record.id, {
    callState: "ended",
    disposition: disposition(data),
    callDurationSeconds: data.duration_seconds ?? 0,
    callEndedAt: new Date().toISOString(),
  });

  // Free a slot in your outbound worker pool here, not on the 201.
  await pool.release(data.call_id);
}

What the call achieved: call.outcome #

call.ended says how the line ended, not what was said. Every finished AI call is then read, and the reading arrives on call.outcome — usually within a minute, sometimes before call.ended. It carries your metadata, so it can go straight to the CRM record:

{
  "id": "evt_9f2c4f3a7b28d05e91c4a761",
  "type": "call.outcome",
  "created_at": "2026-10-14T05:36:02Z",
  "tenant_id": "ten_01JA4M8Q2V7K9X3D5N6P1R0TZB",
  "data": {
    "call_id": "call_01JF9T7Y1A5C9E3G7J1L5N9QRS",
    "direction": "outbound",
    "to": "+919811204587",
    "disposition": "completed",
    "goal_met": "yes",
    "summary": "Rahul renewed the AMC for his split AC and asked for the payment link on WhatsApp.",
    "sentiment": "positive",
    "next_step": "send_whatsapp",
    "next_step_reason": "He asked for the payment link.",
    "fields": {},
    "captured": 0,
    "expected": 0,
    "metadata": { "crm_record_id": "opp_88213" },
    "event_id": "evt_01JF9T9A3C7E1G5J9L3N7Q1S5U"
  }
}

async function onCallOutcome(data) {
  // Your own id comes back in metadata; fall back to the stored call_id.
  const record =
    (data.metadata?.crm_record_id && (await crm.findById(data.metadata.crm_record_id))) ||
    (await crm.findByCallId(data.call_id));
  if (!record) return;

  await crm.update(record.id, {
    result: data.disposition,               // completed, partial, callback_requested, …
    goalMet: data.goal_met,                 // yes | no | unclear
    callSummary: data.summary ?? "",
    nextStep: data.next_step,               // none | call_back | send_whatsapp | human_follow_up
    answers: data.fields ?? {},
  });
}

A call can be read again — someone presses Re-read in the console — and each reading sends a new call.outcome. Keep the latest per call_id. To ask the agent for specific answers (a renewal decision, a preferred slot), send a capture with the call; Call outcomes covers it, and the field-by-field payload is in the Event reference.

Two things not to build on:

• The top-level summary on GET /calls/{call_id} is not populated. The field exists on the call and comes back null. The written summary of what happened is result.summary there, filled in once the call has been read (usually within a minute of it ending), and summary on call.outcome. See Call outcomes.
• recording_uri only exists if recording is enabled, which is off by default and requires an explicit opt-in per number. When it is on, callers hear a spoken notice before the greeting. See How voice works.

Cancelling a call in flight #

If the CRM stage changes again while the phone is still ringing, hang up:

curl -X POST https://services.amomic.in/api/v1/calls/call_01JQRS4T8XZ0AB1CD2EF3GH4/hangup \
  -H "Authorization: Bearer $AMOMIC_API_KEY"

{ "call_id": "call_01JQRS4T8XZ0AB1CD2EF3GH4", "ended": true }

ended: false means the call was already over — it is not an error, and it is the answer you get if you race the customer hanging up. call.ended still fires either way.

Going to production #

• Call yourself first. Place a real call to your own mobile with the real purpose text and listen to the whole thing. Reading the brief is not the same as hearing the agent open with it.
• Put the compliance check in the trigger, not in a runbook. It is the one part of this flow the platform will not do for you.
• Cap attempts per contact per day in your own code and treat rejected as a stop signal.
• Alert on no_agent_deployed and workspace_suspended separately. Both mean every call will fail identically until a human acts.
• Watch the Calls page in the console during the first batch. It shows each call's outcome and duration as they finish.

Next #