Call Handling API

An inbound call has to be answered by something. These five surfaces are that something: a flow (a step-by-step graph), a menu ("press 1 for sales"), a queue (hold until someone is free), a voicemail message for outbound calls that reach a machine, and a reputation check on the number itself.

Credential class: dashboard JWT or a cm_ keyCopy Anchor Link

Authorization: Bearer cm_your_api_key

Every endpoint on this page takes either. API-key callers need:

Call handling is an attribute of telephony, so it reuses those two scopes and adds none. Base URL for every example: https://api.callmissed.com. Errors are {"detail": "..."}. Every create (POST on a collection) returns 201 Created, and every DELETE of a flow, menu, queue, member or voicemail message returns 204 No Content.

How a number picks oneCopy Anchor Link

A number's binding is stored on the number itself, and each surface has its own attach call:

Attaching takes effect from the next inbound call on that number. A flow answers only once it is published, and a menu only while it is enabled; until then the number answers with its agent as usual.

If one number carries more than one binding, the first that can answer wins: a published flow, then an enabled menu, then the queue, then an active squad (its entry agent answers). A number answered by a flow or menu reaches its queues through a key or a route step instead of putting every caller on hold first.

Detach is idempotent: unbinding a number that is not bound is a success, not an error. Deleting the flow, menu or queue a number points at is also safe — the call simply answers normally, because the binding is re-checked against your own rows on every call.

Both ids are checked against your account on every one of these calls, so a number can never be pointed at another account's flow, menu or queue.

What the caller experiencesCopy Anchor Link

A flow or menu runs before any agent speaks. The caller hears the prompt (your prompt_audio_url recording if you set one, otherwise the prompt text read aloud) and presses a key. A key pressed while the prompt is still playing is accepted straight away. Pressing nothing within timeout_seconds, or a key that maps nowhere, replays the prompt until max_retries is spent. If the call is recorded, the recording notice plays before the first prompt.

Where each destination takes the call:

If a step cannot complete — a menu deleted mid-call, an agent that is switched off, or an agent that runs on a different voice tier or a different kind of voice model from the number's agent (a speech-to-speech model in place of a standard one, or the reverse) — the number's own agent answers the call instead, so a caller is never left in silence. Use agents on the same voice tier and model kind as the number's agent for bot destinations.

Call flowsCopy Anchor Link

A flow is a directed graph of steps. Each step is a node with a type and a config; edges connect them.

The flow objectCopy Anchor Link

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "name": "Front desk",
  "description": "Business hours, then a menu",
  "graph": { "entry": "hello", "nodes": [], "edges": [] },
  "published_graph": { "entry": "hello", "nodes": [], "edges": [] },
  "version": 3,
  "published": true,
  "published_at": "2026-09-08T12:00:00Z",
  "created_at": "2026-09-01T09:00:00Z",
  "updated_at": "2026-09-08T11:59:00Z"
}

Node typesCopy Anchor Link

A destination — used by route.destination and by each key in a dtmf_menu's options — is {"type": ..., "value": ..., "label": ...}:

hours is keyed by mon tue wed thu fri sat sun, each a list of up to 6 {"start": "09:00", "end": "18:00"} windows. A day with no windows is closed all day. An unknown timezone, a malformed HH:MM, or a holiday that is not a real date is rejected at write time rather than silently misrouting a call later.

GET /api/v1/call-flowsCopy Anchor Link

Your flows, newest first. Requires telephony:read.

curl https://api.callmissed.com/api/v1/call-flows \
  -H "Authorization: Bearer cm_your_api_key"

POST /api/v1/call-flowsCopy Anchor Link

Create a flow. Requires telephony:write. It answers nothing until it is published and a number is attached, so a half-built graph is safe to save.

curl -X POST https://api.callmissed.com/api/v1/call-flows \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Front desk",
    "graph": {
      "entry": "hello",
      "nodes": [
        {"id": "hello", "type": "greeting", "config": {"prompt": "Thanks for calling Acme."}},
        {"id": "pick", "type": "dtmf_menu", "config": {
          "prompt": "Press 1 for sales, 2 for support.",
          "options": {
            "1": {"type": "bot", "value": "8f14e45f-ceea-467a-9f6b-0f9a7bd1c111", "label": "Sales"},
            "2": {"type": "queue", "value": "3d9a1b22-0f4c-4a61-9d33-3f2a51b0c222", "label": "Support"}
          }
        }}
      ],
      "edges": [{"from": "hello", "to": "pick", "on": "next"}]
    }
  }'

Structural problems are 422 with a message naming the node: a duplicate node id, an edge pointing at a node that does not exist, a branch the node type cannot take, or two branches of the same name leaving one node. A destination id that is not yours is 404.

entry may be omitted — the first node becomes the entry point — but an explicit one is clearer.

GET /api/v1/call-flows/{flow_id}Copy Anchor Link

One flow, with both the draft and the published snapshot. Requires telephony:read.

PATCH /api/v1/call-flows/{flow_id}Copy Anchor Link

Update the draft. Requires telephony:write. Live calls keep hearing the published snapshot until you publish again.

name, description and graph are all optional; an omitted field keeps its stored value and "description": "" clears it. graph is replaced wholesale, because a canvas is edited as one unit and a per-node merge would make deleting a node impossible. Send the whole graph.

POST /api/v1/call-flows/{flow_id}/publishCopy Anchor Link

Snapshot the draft into published_graph, bump version, and start answering real calls with it. Requires telephony:write.

The draft is re-validated first — including re-checking that every destination still belongs to you — so a queue deleted since the flow was drawn is caught here instead of on a live call. A flow with no nodes, or whose entry node is missing, is refused with 422.

curl -X POST https://api.callmissed.com/api/v1/call-flows/{flow_id}/publish \
  -H "Authorization: Bearer cm_your_api_key"

POST /api/v1/call-flows/{flow_id}/unpublishCopy Anchor Link

Stop answering with this flow. Requires telephony:write. The snapshot and the version are kept, so re-publishing is one call. Idempotent, and attached numbers answer normally in the meantime.

DELETE /api/v1/call-flows/{flow_id}Copy Anchor Link

Delete the flow. Requires telephony:write. Numbers still carrying it answer normally from the next call.

POST /api/v1/call-flows/{flow_id}/simulateCopy Anchor Link

Dry-run one step and get back the instruction a real call would receive. Requires telephony:read. Nothing is dialled and nothing is charged.

Webhook nodes are not called during a simulation. Such a node takes its ok branch and the response lists it under simulated_webhook_nodes, so you never mistake a dry run for a real delivery.

curl -X POST https://api.callmissed.com/api/v1/call-flows/{flow_id}/simulate \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"event": "dtmf", "node_id": "pick", "pressed_key": "1"}'

Call menusCopy Anchor Link

A standalone press-1-for-sales step, for when a whole flow is more than you need. Same idea as a flow's dtmf_menu node, but it is its own object and attaches to a number directly.

{
  "id": "3d9a1b22-0f4c-4a61-9d33-3f2a51b0c222",
  "name": "Main menu",
  "prompt": "Press 1 for sales, 2 for support.",
  "prompt_audio_url": null,
  "options": {
    "1": { "type": "bot", "value": "8f14e45f-ceea-467a-9f6b-0f9a7bd1c111", "label": "Sales" }
  },
  "timeout_seconds": 5,
  "invalid_action": "reprompt",
  "max_retries": 2,
  "enabled": true,
  "created_at": "2026-09-01T09:00:00Z",
  "updated_at": "2026-09-01T09:00:00Z"
}

options is replaced wholesale on PATCH, so send every key you want to keep. A menu pointing at itself is refused (422) — it would loop the caller forever. A key outside 1–9, or a destination missing its value, is also 422; a destination id that is not yours is 404.

curl -X POST https://api.callmissed.com/api/v1/call-menus \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main menu",
    "prompt": "Press 1 for sales, 2 for support.",
    "options": {
      "1": {"type": "bot", "value": "8f14e45f-ceea-467a-9f6b-0f9a7bd1c111", "label": "Sales"},
      "2": {"type": "queue", "value": "3d9a1b22-0f4c-4a61-9d33-3f2a51b0c222", "label": "Support"}
    }
  }'

Call queuesCopy Anchor Link

A queue holds callers until someone on its roster is free.

{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "name": "Support",
  "strategy": "round_robin",
  "hold_audio_url": null,
  "position_announce_seconds": null,
  "max_wait_seconds": 300,
  "overflow_action": "voicemail",
  "enabled": true,
  "created_at": "2026-09-01T09:00:00Z",
  "updated_at": "2026-09-01T09:00:00Z"
}

While a caller holds, the agent does not listen to them and the AI per-minute fee does not run; it starts when the caller is routed to an agent. A caller routed to a person is put through to them live when that member has a transfer_target (see the roster below); otherwise, or if nobody answers, they are promised a callback and the request appears in your handoffs.

The rosterCopy Anchor Link

A member is either an agent (kind: "ai", bot_id) or a person in your workspace (kind: "human", user_id). Either way the id must belong to your account, which is what stops a queue routing calls to somewhere else.

How a person is reached: a member stores a transfer-target name, never a phone number. When a caller is routed to them, the name is looked up in the transfer targets of the agent answering the dialed number, and the number saved there is called. A name that agent does not have, or a person who does not pick up, falls back to the callback request. See live transfer for how transfer targets are set up and billed.

PATCH changes priority, max_concurrent, enabled and transfer_target only — kind, bot_id and user_id are immutable, so point a queue at a different answerer by removing the member and adding a new one. Raising max_concurrent or re-enabling a member pulls waiting callers in straight away rather than at the next release.

curl -X POST https://api.callmissed.com/api/v1/call-queues/{queue_id}/members \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"kind": "ai", "bot_id": "8f14e45f-ceea-467a-9f6b-0f9a7bd1c111", "max_concurrent": 3}'

curl -X POST https://api.callmissed.com/api/v1/call-queues/{queue_id}/members \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"kind": "human", "user_id": "c4ca4238-a0b9-4382-8dcc-509a6f75849b", "transfer_target": "Sales"}'

GET /api/v1/call-queues/{queue_id}/liveCopy Anchor Link

Who is holding right now. Requires telephony:read. limit is 1–200, default 50.

{
  "queue_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "strategy": "round_robin",
  "waiting": 2,
  "members_total": 4,
  "members_free": 1,
  "longest_wait_seconds": 96,
  "callers": [
    {
      "entry_id": "1f0c2e77-1b2a-4a55-8f0e-9b1c2d3e4f50",
      "caller_suffix": "…4321",
      "position": 1,
      "waiting_seconds": 96,
      "priority": 100,
      "enqueued_at": "2026-09-08T12:00:00Z"
    }
  ]
}

A caller's full number is never returned here — only the last four digits, which is enough to match someone on screen. This is a point-in-time read; poll it no faster than you need.

Voicemail messagesCopy Anchor Link

What an outbound call leaves when an answering machine picks up. Needs calling enabled on your account.

{
  "id": "2f8a7c10-5b6d-4e3f-8a1b-7c9d0e1f2a3b",
  "tenant_id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "name": "Missed you — sales",
  "text": "Hi, this is Acme returning your call. We'll try again tomorrow.",
  "voice": null,
  "language": "en-IN",
  "audio_state": "pending",
  "created_at": "2026-09-01T09:00:00Z",
  "updated_at": "2026-09-01T09:00:00Z"
}

Changing text throws away the clip made from the old words, and the next use re-synthesises once. Without that, a call would keep playing the old message forever.

Number reputationCopy Anchor Link

Whether one of your numbers has been reported as spam, and what is still open against it. Needs calling enabled on your account.

GET /api/v1/reputation/{number}Copy Anchor Link

Requires telephony:read. {number} is one of your numbers in E.164, with or without the leading +. A number you do not own returns 404 — never 403 — so nobody can probe for other accounts' numbers.

{
  "phone_number": "919000000000",
  "status": "pending",
  "complaints": [
    {
      "reference_id": "PUCC-000123",
      "status": "pending",
      "to_number": "919111111111",
      "initiation_date": "2026-09-05",
      "complaint_category": "promotional",
      "opt_in_proof": null,
      "rejection_reason": null,
      "actionable": true
    }
  ],
  "actionable_count": 1,
  "last_checked": "2026-09-08T11:30:00Z",
  "stale": false
}

POST /api/v1/reputation/{number}/remediateCopy Anchor Link

Upload opt-in proof for one complaint. Requires telephony:write. multipart/form-data:

curl -X POST https://api.callmissed.com/api/v1/reputation/919000000000/remediate \
  -H "Authorization: Bearer cm_your_api_key" \
  -F 'reference_id=PUCC-000123' \
  -F '[email protected]'

{
  "phone_number": "919000000000",
  "reference_id": "PUCC-000123",
  "status": "in_review",
  "message": "Opt-in proof uploaded and the complaint is under review. ..."
}

A file over 10 MB returns 413. Only the file's type and size are checked at upload; the document itself is reviewed afterwards, so a 200 means "under review", not "cleared". The proof must show your business logo, the opt-in date (within the six months before the complaint) and the complainant's exact number, or the review declines it.

Do this from an AI assistant insteadCopy Anchor Link

Every read and write on this page except the two file uploads is also a tool on the Account MCP Server, so an assistant you have connected can build a flow, wire a menu, staff a queue and publish the lot without you writing a single request.