Skip to main content
An inbound agent is an agent with type: "inbound". When you attach an inbound agent to a phone number, every incoming call to that number is answered by CallingBox and handed to the agent. You don’t make an API call to start an inbound call. The caller dials your number, CallingBox looks up the inbound agent attached to that number, and the conversation starts.

​
Routing rule

Each phone number can have at most one inbound agent. That agent answers every incoming call to the number.

​
Set up an inbound agent

1

Purchase or pick a number

You need at least one active number. See Numbers.
2

Create the inbound agent

Configure the behavior once: persona, instructions, voice, returns, tools, voicemail action. Attach the number at creation time.
from callingbox import Callingbox

client = Callingbox()

agent = client.agents.create(
    name="Front desk",
    type="inbound",
    instructions=(
        "Answer calls for Bright Smiles Dental. Help with hours, "
        "directions, and appointment questions. If the caller wants a "
        "human, take a message with their name and callback number."
    ),
    returns={
        "caller_name": "string",
        "reason": "string",
        "callback_number": "string",
    },
    voicemail_action="hangup",
    number_ids=["pn_xyz789"],
)
3

Call the number

Dial the attached number from any phone. CallingBox picks up and the agent starts the conversation immediately.

​
What happens per inbound call

  1. A caller dials your number.
  2. CallingBox looks up the inbound agent attached to that number. If none is attached, the call is rejected.
  3. A call record is created with direction: "inbound" and agent_id set to the inbound agent.
  4. CallingBox answers, runs the agent (persona, instructions, voice, tools, language), and drives the conversation.
  5. When the call ends, CallingBox extracts the agent’s returns schema from the transcript and updates the call record.
  6. Webhooks fire (call.answered, call.completed, etc.) to the agent’s webhook_url and any account-wide endpoints.

​
Update the agent’s behavior

Edits to the agent apply to the next call. In-progress calls continue with the config they started with. 
client.agents.update(
    agent.id,
    instructions="New instructions starting now.",
)

​
Swap numbers

Detach and attach numbers as you move the agent to a different line. The number starts routing to the new inbound agent as soon as it’s attached. 
client.agents.detach_number(agent.id, number_id="pn_old")
client.agents.attach_number(other_agent.id, number_id="pn_old")

​
Retrieve inbound calls

Inbound calls show up in the same GET /v1/calls list as outbound calls. Filter by direction or by agent_id in the dashboard, or by id in the API. 
for call in client.calls.iter_calls():
    if call.direction == "inbound" and call.agent_id == agent.id:
        print(call.id, call.to_number, call.result)

Agents

The agent primitive in depth.

Outbound calls

Dispatch a call from an outbound agent.

Structured results

Define the returns schema on your agent.

Webhooks

Get notified when an inbound call finishes.