Skip to main content
The API Quickstart covers outbound calls. This guide does the mirror image: make an agent answer calls. You’ll link one of your phone numbers to an agent so every inbound call is picked up automatically.
You need a phone number on your account first. Buy one from the dashboard or via POST /phone-numbers/buy, or bring your own through SIP trunking. Indian numbers also require compliance.

​
Prerequisites

  • A Bolna API key (export BOLNA_API_KEY="bn-xxxx")
  • An agent_id to answer calls (create one via the API Quickstart or the dashboard)
  • At least one phone number on your account
For inbound, give the agent an inbound-appropriate welcome message — e.g. “Thanks for calling Acme, how can I help?” — rather than an outbound opener.
1

Find your phone number's ID

The link call needs the number’s id, not the number itself. List your numbers:
curl https://api.bolna.ai/phone-numbers/all \
  -H "Authorization: Bearer $BOLNA_API_KEY"
Response (array)
[
  {
    "id": "3c90c3cc0d444b5088888dd25736052a",
    "phone_number": "+19876543210",
    "telephony_provider": "twilio",
    "agent_id": null
  }
]
Copy the id of the number you want to use.
2

Link the agent to the number

Associate your agent with the phone number. After this, inbound calls to that number are answered by the agent.
curl https://api.bolna.ai/inbound/setup \
  -H "Authorization: Bearer $BOLNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "YOUR_AGENT_ID",
    "phone_number_id": "3c90c3cc0d444b5088888dd25736052a"
  }'
Response
{
  "url": "https://api.bolna.ai/inbound_call?agent_id=…&user_id=…",
  "phone_number": "+19876543210",
  "id": "3c90c3cc0d444b5088888dd25736052a"
}
3

Call the number

Dial the number from any phone — your agent answers with its welcome message and starts the conversation. After the call, retrieve the transcript exactly like outbound: poll GET /executions/{id} or use a webhook.

​
Optional: IVR routing

For Plivo numbers you can add an ivr_config to the same POST /inbound/setup request to play a menu and route callers to different agents (by department, language, etc.). See IVR for Inbound Calls. To stop an agent from answering a number, call POST /inbound/unlink with the phone number ID.

​
Run the setup as a script

The dependency-free helper script automates listing numbers and linking the agent: 
export BOLNA_API_KEY="bn-xxxx"
export BOLNA_AGENT_ID="your-agent-id"
python3 bolna_inbound_setup.py          # auto-pick your first number
python3 bolna_inbound_setup.py --list   # just list numbers
python3 bolna_inbound_setup.py --dry-run

​
Next steps

Identify callers

Match incoming numbers to your CRM and preload customer data.

Inbound settings

Spam prevention, caller matching, and call limits.

IVR menus

Route callers to different agents with a keypad menu.

Bring your own SIP trunk

Use your existing carrier numbers for inbound.