Calls

Your agent picks up the phone and calls someone. The request returns in well under a second; the conversation takes minutes. Everything about using this endpoint follows from that gap.

When you use this #

A call is the right tool when the answer needs a person's attention now and a message would sit unread — a technician visit that needs confirming today, an AMC that lapses this week, a high-value order that stalled at checkout, a lead that filled a form ninety seconds ago. Your CRM or workflow engine already knows the moment; this endpoint is the trigger.

The whole surface is three endpoints:

All three require the calls:write scope, including the read: there is no separate read scope for calls. See Scopes.

There is no list endpoint. You cannot enumerate calls over the API; you track the call_id values you created, or you consume the call.started, call.ended and call.outcome webhooks.

Parameters #

There is no channel field. Voice is the only dialable channel, and it is resolved for you.

How to is read #

to is screened, and the number that passes the screen is the number dialled.

• With a leading +, it is read as an international number.
• Without one, it is first tried as a number in your workspace's country. If it is not a valid number there, it is read as international digits. In an India workspace, 9876543210 becomes +919876543210, and 919876543210 is read as +91 98765 43210.
• A number that cannot be read either way is refused with 400 and the message That destination number isn't usable. One shorter than 8 digits is refused with That destination number is too short. Neither carries a details.reason.
• Calls go only to countries enabled for outbound calling, and some number ranges (satellite and premium-rate ranges among them) are blocked. See the failures below.

The response's to is the number as dialled, as + and digits. Store that, not what you sent.

Reserved metadata keys #

Three keys in metadata mean something to the call record. campaign_id (with campaign_name) labels the call as a campaign call in the console, and callback_id labels it as a follow-up. A call labelled either way is no longer treated as one your integration placed, so its call.outcome webhook does not carry your metadata. Use other names, such as lead_id or job_id.

The agent comes from the number, not from agent_id #

This trips up everyone once, so it is worth being blunt about.

A phone number in your workspace has exactly one agent deployed to it. When you place a call, the caller-ID number is resolved first — from from_number if you supplied one, otherwise the workspace's first active number — and the agent deployed to that number is the agent that speaks. agent_id does not choose anything.

What agent_id does is assert your expectation. If you pass one and it does not match the agent actually deployed to that number, the call is refused with 412 failed_precondition and this details object:

{
  "reason": "agent_number_mismatch",
  "deployed_agent_id": "bot_01JQRS4T8XZ0AB1CD2EF3GH4"
}

That is the point of the field. If your system cares which agent talks to a customer — and for anything money-adjacent it should — pass both from_number and agent_id together. Then a deployment change made in the console on a Tuesday afternoon turns into a loud 412 in your logs instead of the wrong agent quietly having the wrong conversation. details.deployed_agent_id tells you what is actually there.

To route to a different agent, call from a different number. One number, one agent.

What purpose does #

purpose is free text, up to 500 characters, and it reaches the agent as the reason for the call. It is added to the agent's instructions for the whole conversation, and it is stored on the call record.

Write it as an instruction to a colleague, not as a script:

{ "purpose": "Confirm Asha's AC service visit on Thursday 15 October between 11am and 1pm, and offer another slot if it does not suit." }

For the steps of the call, use script; for what you want to know by the end of it, use capture. The three work together: purpose is why, script is how, capture is what to bring back. Call outcomes covers script, details and capture in full.

Two things it is not. It is not the greeting — the opening line is a fixed template that identifies your business, discloses that the caller is a virtual assistant, and asks whether now is a good time, in that order. And it is not the agent's knowledge; the agent still answers from the knowledge base bound to it. purpose sets the errand, nothing else.

ring_seconds #

Bounded to 10–90, default 30. Below 10 the destination often has not finished routing to the handset; above 90 you are holding one of your 10 concurrent call slots for someone who is not going to answer. A call that rings out never reaches the agent and finalises with a zero duration and an outcome such as no_answer or busy.

Example #

Calling a customer the moment your service desk books their AC service visit, to confirm the slot.

curl -X POST https://services.amomic.in/api/v1/calls \
  -H "Authorization: Bearer $AMOMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: job-VH-4821-confirm-call" \
  -d '{
    "to": "+919876543210",
    "from_number": "+918047261935",
    "agent_id": "bot_01JQRS4T8XZ0AB1CD2EF3GH4",
    "purpose": "Confirm the AC service visit for job VH-4821 on Thursday 15 October between 11am and 1pm, and offer another slot if it does not suit.",
    "details": { "Name": "Asha Menon", "Appliance": "Split AC, 1.5 ton", "Job": "VH-4821" },
    "ring_seconds": 40,
    "metadata": { "job_id": "VH-4821" }
  }'

POST /calls honours Idempotency-Key, and you should always send one. A retry after a timeout replays the stored 201 rather than dialling the customer twice, which, unlike a duplicate message, is a phone ringing in someone's pocket a second time. See Idempotency.

Response #

{
  "call_id": "call_01JQRS4T8XZ0AB1CD2EF3GH4",
  "status": "ringing",
  "direction": "outbound",
  "to": "+919876543210",
  "from_number": "+918047261935",
  "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 }
}

to and from_number are the numbers actually used, as + and digits. agent_id echoes what you sent, so it is null when you sent none, even though an agent will speak; read the call back to see which. capture echoes the capture you sent, with every field key filled in, or null when you sent none.

Store call_id. It is the only handle you get, and there is no way to look a call up by phone number or by your own metadata.

---

Read the current state of one call. Scope calls:write. No query parameters. Any call in the workspace can be read this way, including inbound calls and campaign calls, as long as you have its call_id.

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

{
  "call_id": "call_01JQRS4T8XZ0AB1CD2EF3GH4",
  "status": "completed",
  "direction": "outbound",
  "to": "+919876543210",
  "from_number": "918047261935",
  "agent_id": "bot_01JQRS4T8XZ0AB1CD2EF3GH4",
  "duration_seconds": 96,
  "outcome": "caller_hangup",
  "summary": "Asha confirmed the AC service visit for Thursday and asked the technician to call from the gate.",
  "recording_uri": null,
  "started_at": "2026-10-14T05:50:04.812311+00:00",
  "ended_at": "2026-10-14T05:51:40.930118+00:00",
  "capture": null,
  "result": {
    "state": "ready",
    "disposition": "completed",
    "goal_met": "yes",
    "success": null,
    "summary": "Asha confirmed the AC service visit for Thursday and asked the technician to call from the gate.",
    "sentiment": "positive",
    "next_step": "none",
    "next_step_reason": null,
    "fields": {},
    "captured": 0,
    "expected": 0,
    "missing_required": [],
    "read_at": "2026-10-14T05:52:21.004512+00:00"
  }
}

A call_id that does not exist, or belongs to another workspace, returns 404 not_found with the message Call not found. The two cases are answered identically on purpose.

Do not switch exhaustively on status #

status is typed as a plain string. No closed enum is declared, so no closed list is published. New lifecycle states can appear without a version bump, and code that throws on an unrecognised value will eventually throw in production at 3 a.m.

Give yourself a default branch:

switch (call.status) {
  case "completed":
    return "done";
  case "failed":
    return "failed";
  default:
    // ringing, in_progress, a handoff, or a state added later: still live.
    return "live";
}

The field that tells you how the line ended is outcome, and it is only meaningful once the call has ended. What the conversation achieved is in result:

Unanswered calls finalise as status: "completed" with duration_seconds: 0 and one of the network outcomes above. A completed status therefore does not mean a conversation happened. Check duration_seconds and outcome together, or read result.disposition.

Getting the outcome: poll, or subscribe #

Subscribe. Register a webhook for call.ended and you are told the moment the call finalises. Register call.outcome as well and you get the reading (disposition, summary and every answer to your capture) as soon as it lands, usually within a minute after that. This is the right answer for anything that needs to react: updating a CRM, reopening a job, scheduling another try. See Event reference for exactly which fields each event carries, and remember that delivery is at-least-once, so dedupe on the event id.

Poll. If you cannot receive webhooks, GET /calls/{call_id} works, but poll gently: wait ring_seconds before your first read, check every few seconds, and stop as soon as ended_at is set. If you want the answers, carry on until result.state is no longer pending. Every poll spends one of your 120 requests per minute, and a tight loop across a batch of calls will hit the rate limit long before the calls finish.

import time

import requests


def wait_for_reading(call_id: str, headers: dict, ring_seconds: int = 30, timeout_s: int = 900):
    time.sleep(ring_seconds)  # nothing to see before this
    deadline = time.monotonic() + timeout_s
    while time.monotonic() < deadline:
        call = requests.get(f"{BASE}/calls/{call_id}", headers=headers, timeout=15).json()
        if call["ended_at"] is not None and call["result"]["state"] != "pending":
            return call
        time.sleep(10)
    raise TimeoutError(f"{call_id} was not read within {timeout_s}s")

---

End a call. Scope calls:write. No request body.

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 is true when the call's status was ringing or in_progress and a hang-up was sent. It is false for any other status, and nothing is done. That covers a call that is already over, which is a normal, successful answer, not an error, so hangup is safe to call repeatedly. It also covers a call your team has taken over (human_handoff, human_active): the API does not cut off a member of your team mid-call.

An unknown call_id returns 404 not_found with Call not found.

Use it when your own system learns the call is pointless mid-flight: the customer just rescheduled online, someone else already reached them, or your operator cancelled the job.

Failures #

After the key, scope and request checks, guards run in this order, and the first one that trips is the error you get.

Three different 429s #

They mean different things and want different responses. None carries a Retry-After header, and none is a bug in your request.

• reason: "rate_limited": you are calling the API too fast. 120 requests per minute per key. Slow your loop down.
• reason: "call_concurrency": you are calling people too fast. A workspace runs at most 10 live calls at once. Your loop is fine; your queue drain rate is not. Wait for calls to end, or spread the batch over time. See The other 429: concurrent calls.
• reason: "daily_call_budget": the workspace has placed as many outbound calls today as its safety limit allows. Each call reserves its maximum length in minutes against the limit when it is placed. Do not retry today; read details to see which limit you met.

The 412 family is configuration, not weather #

voice_not_configured, workspace_suspended, wallet_empty, channel_dormant, no_phone_number, no_agent_deployed, agent_number_mismatch and unsupported_channel all return exactly the same result if you retry in ten seconds. Do not put them behind a backoff. Page someone, or fail the job with the reason attached. The fix is always in the console. The two billing ones are covered in What happens when you run out.

Related #