Skip to main content
Outbound calls are executions of an outbound agent. The agent owns the persona, instructions, voice, returns schema, tools, and caller ID. Dispatching a call is cheap: you reference the agent by id, pass the destination number, and CallingBox places the call.

​
Prerequisite: an outbound agent

Before you can dispatch a call, you need an outbound agent with at least one attached number. See Agents for the full create flow. Minimal example: 
from callingbox import Callingbox

client = Callingbox()

agent = client.agents.create(
    name="Appointment reminders",
    type="outbound",
    instructions="Confirm dental appointments. Offer to reschedule if needed.",
    returns={"confirmed": "boolean", "reschedule_to": "string"},
    number_ids=["pn_abc123"],
    primary_number_id="pn_abc123",
)

​
Dispatch a call

POST /v1/calls takes an agent id and a destination number. Everything else is optional.

​
Request fields

FieldTypeRequiredDefaultDescription
agent_iduuidYesn/aThe outbound agent to run for this call.
tostringYesn/aDestination number, E.164 format (e.g. +15551234567).
from_numberstringNoagent’s primary_number_idCaller ID override. Must be another number attached to the same agent.
instructionsstringNoagent’s defaultPer-call instructions. Replaces the agent’s default instructions for this call. Not merged.
contextobjectNo{}Background info the agent can reference mid-conversation.
webhook_urlstringNoagent’s defaultPer-call webhook override. Defaults to the agent’s webhook_url.
metadataobjectNo{}Arbitrary key/value data you can read back off the call record.
persona, voice, language, returns, tools, and voicemail_action are not accepted on POST /v1/calls. They live on the agent. If you need to change them, update the agent or create a different one.

​
Minimal example

call = client.calls.create(
    agent_id=agent.id,
    to="+15551234567",
)
print(call.id, call.status)

​
Per-call overrides

​
instructions: replace the agent’s task

Use per-call instructions when you want the same agent personality but a different task on this one call. The per-call value wholly replaces the agent’s default. It does not merge. 
{
  "agent_id": "agent-uuid-here",
  "to": "+15551234567",
  "instructions": "Call to confirm a dental appointment tomorrow at 2pm for Maria Lopez. If she wants to reschedule, ask for her preferred date and time."
}
One goal per call. If your prompt tries to confirm an appointment, collect feedback, and upsell at the same time, split it into separate calls (or separate agents).

​
context: per-call background info

Context is JSON the agent has access to mid-call. It doesn’t go into the instructions; the agent just knows it. 
{
  "agent_id": "agent-uuid-here",
  "to": "+15551234567",
  "context": {
    "patient": "Maria Lopez",
    "doctor": "Dr. Chen",
    "appointment_date": "2026-04-22",
    "appointment_time": "2:00 PM"
  }
}

​
from_number: pick a caller ID

If you omit from_number, the call uses the agent’s primary_number_id. To use a different one, pass any other number attached to the same agent. 
{
  "agent_id": "agent-uuid-here",
  "to": "+15551234567",
  "from_number": "+15557654321"
}
If you pass a number that isn’t attached to the agent, the request fails with 400.

​
webhook_url: per-call webhook

Override the agent’s default webhook for this call only. See Webhooks for the full delivery model. 
{
  "agent_id": "agent-uuid-here",
  "to": "+15551234567",
  "webhook_url": "https://your-server.com/callingbox-webhook"
}

​
Patterns

​
Appointment confirmation

{
  "agent_id": "agent-uuid-here",
  "to": "+15551234567",
  "instructions": "Confirm the patient's appointment tomorrow at 2pm.",
  "context": { "patient": "Maria Lopez", "doctor": "Dr. Chen" }
}

​
Lead qualification

{
  "agent_id": "agent-uuid-here",
  "to": "+15559876543",
  "instructions": "Qualify this lead for the enterprise plan. Ask about team size, current tools, and timeline.",
  "context": { "lead": "Sarah Kim", "company": "Acme Corp" }
}

​
Payment collection

{
  "agent_id": "agent-uuid-here",
  "to": "+15554567890",
  "instructions": "Follow up on overdue balance. Offer a payment plan if needed.",
  "context": { "customer": "Roberto Méndez", "balance": 4850.00, "days_overdue": 45 }
}

Agents

The agent primitive. Where persona, returns, and tools live.

Structured results

How the returns schema (on the agent) becomes JSON.

Webhooks

Polling vs webhooks for getting results.

Call object

Every field on the call response.