Make voice AI call API
Learn how to initiate outbound phone calls using Bolna Voice AI agents. Start making phone calls using the agent ID and recipient’s phone number.
execution_id you use to track and retrieve the call result.
Minimal example
Only two fields are required —agent_id and recipient_phone_number. Omit from_phone_number to use your account’s default number.
Realistic example with personalization
Passuser_data to inject variables into your agent’s prompt and welcome message (e.g. {{customer_name}} in the prompt becomes “Asha”):
Call a specific agent version
Calls use the agent’s live version. Passagent_version_id to run the call on another agent version instead, for example to test a version before you make it live. Get the id from List agent versions or from the response of Save as new version.
404 with Agent version not found.
To compare versions on real calls, see A/B test agent versions.
Tracking the call
Use the returnedexecution_id to poll GET /executions/{execution_id} for status. The call goes through these stages:
Common 400 errors
agent_version_id that doesn’t exist, belongs to another agent or was deleted returns 404 (see Call a specific agent version).
Calling from a newly bought number
Providers sometimes take up to 3 minutes to activate a number after you buy it. Until then, a call from it returns429 with how long to wait:
retry_after_seconds. A call with a scheduled_at after the number activates is accepted right away. A scheduled call that would dial before then gets the same 429, and its message names the earliest time you can schedule it for.Authorizations
Body
Make a phone call from agent
Phone number of the recipient along with country code (in E.164 format)
Run this call on a specific agent version instead of the live one, for example to test a version before making it live. Use an id from List agent versions. Omit it to use the live version. Returns 404 if the version doesn't exist, belongs to another agent or was deleted.
Phone number of the sender along with country code (in E.164 format). Optional — if omitted, Bolna uses the account's default number.
Configuration for auto-retry of failed calls. See auto-retry documentation for details.
Response
agent status response