Skip to main content
Here’s what happens between your API request and the JSON you get back.

​
Outbound lifecycle

1

Configure an agent

An outbound agent owns the persona, instructions, voice, language, returns schema, tools, and attached numbers. You create it once and dispatch many calls against it. See Agents.
2

You dispatch a call

POST /v1/calls with agent_id and to (destination). Optionally override instructions for this call, pass context, pick a different from_number (must already be attached to the agent), or set a per-call webhook_url.
3

CallingBox dials the number

The call goes out right away. If the line is busy, goes to voicemail, or nobody picks up, CallingBox catches that and updates the status. You’re only billed for time someone actually answers.
4

The agent has the conversation

Once the person picks up, a real-time voice loop kicks in:
  • Speech-to-text transcribes what the person says
  • The language model generates a response using the agent’s persona, instructions, and your context
  • Text-to-speech speaks the reply
This continues until the goal is reached or the call wraps up on its own.
5

Data gets extracted

After the call ends, CallingBox reads the transcript against the agent’s returns schema and extracts the fields. If the agent asked for {"confirmed": "boolean"}, you’d get back something like {"confirmed": true}.
6

You get the result

Two options:
  • Poll GET /v1/calls/{id} and read the result field
  • If the agent (or call) has a webhook_url, CallingBox POSTs the full call object to your server when processing finishes

​
Inbound lifecycle

Inbound calls are the mirror image. You configure an inbound agent and attach a number; CallingBox answers automatically when the number rings. See Inbound calls for the full flow.

​
When nobody answers (outbound)

CallingBox detects voicemail, busy signals, and no-answer. The status updates to no_answer, busy, or failed. Voicemail is reported as status: no_answer with answered_by: machine so the dashboard labels it “Voicemail”. By default CallingBox hangs up as soon as voicemail is detected; set voicemail_action: "leave_message" on the agent to keep the line open. No extraction runs, no charge. More detail in Statuses and failures.

Agents

The primitive that owns the behavior.

Outbound calls

All the dispatch fields and per-call overrides.

Structured results

Define a returns schema on the agent and get typed JSON back.

Webhooks

Polling vs webhooks for getting results.