# Write Voice AI Agent Prompts
Source: https://www.bolna.ai/docs/agent-setup/agent-tab
Configure your Bolna Voice AI agent's personality and welcome message. Write effective prompts, use dynamic variables, and set up call hangup conditions.
## What is the Agent Tab?
The Agent Tab is where you define your voice AI agent's personality, welcome message, and conversation behavior. This is the core configuration that controls how your agent greets callers and responds during conversations.
***
## Configuration Options
### Agent Welcome Message
The welcome message is the first thing callers hear when they connect.
A brief, friendly greeting works best—avoid long announcements
Personalize with `{variable_name}` syntax (e.g., `{customer_name}`)
A simple "Hello, thanks for calling!" works well for most use cases. Longer greetings can feel robotic.
***
### Agent Prompt
Define your agent's personality, behavior, and instructions. This is the brain of your voice AI.
| Section | Purpose | Example |
| ---------------- | -------------------------- | ------------------------------------------------------- |
| **Personality** | How the agent should sound | "warm, empathetic, and grounded customer support agent" |
| **Context** | Background about the role | "You are calling on behalf of Acme Corp..." |
| **Instructions** | Specific tasks and flow | "Ask for their order number first..." |
| **Guardrails** | What NOT to do | "Never discuss competitor products..." |
Use `{variable_name}` for dynamic content and `@` to mention [function calling](/tool-calling/introduction) tools in your prompt.
***
### AI Edit Feature
Use AI to refine and improve your prompts automatically.
Click the **AI Edit** button in the top-right of the Agent Prompt section.
Tell the AI what you want to add, remove, or modify in your prompt.
Click **Re-generate Prompt** to apply AI-powered improvements.
Be specific in your change descriptions—for example: "Make the agent more empathetic when handling complaints" or "Add a step to verify the caller's email address."
***
### Prompt Variables
Make your prompts dynamic with personalized data.
| Setting | Description |
| -------------------- | ---------------------------------------------------------------------- |
| **Define Variables** | Use `{variable_name}` syntax in your prompt |
| **Test Variables** | Fill in values for testing before live calls |
| **Timezone** | Set timezone for time-based variables (e.g., `Asia/Kolkata UTC+05:30`) |
Learn more about [using context and variables](/using-context) to personalize calls with caller data.
***
### Hangup Using Prompt
Let your agent intelligently decide when to end calls based on conversation context.
Turn on **Hangup using a prompt** to activate intelligent hangup.
Write conditions that determine when a conversation is complete (e.g., "customer confirmed their order" or "all questions answered").
Without this feature, calls rely on silence detection or timeouts to end. Enable it for more natural conversation endings.
***
## Next Steps
Configure language model and knowledge base
Set up voice and transcription
Best practices for writing prompts
Dynamic personalization with context
# Set Up Webhooks and Post-Call Analytics
Source: https://www.bolna.ai/docs/agent-setup/analytics-tab
Configure webhooks, call summarization, and data extraction for Bolna Voice AI. Push data to your CRM and create custom analytics from every call.
## What is the Analytics Tab?
The Analytics Tab is where you configure webhooks for real-time data, post-call processing tasks, and custom analytics extraction. Automatically summarize conversations, extract structured data, and push execution data to your systems.
***
## Configuration Options
### Push Execution Data to Webhook
**Don't miss real-time updates!** Configure a webhook to receive all execution data as calls happen — essential for CRM integrations and live dashboards.
Enter your webhook URL to automatically receive all execution data for this agent.
Click **[See all events](/polling-call-status-webhooks)** to view the complete list of webhook event types you can receive.
***
### Post Call Tasks
Choose tasks to execute after the agent conversation is complete.
Automatically generate a summary of every conversation. Great for quick review and logging.
Toggle on to enable automatic conversation summarization.
Extract structured data from conversations using custom prompts.
**Example extraction rules:**
```
user_name: Yield the name of the user.
payment_mode: If user is paying by cash, yield cash. If card, yield card.
```
Define clear extraction rules to get consistent, structured data from every call.
Use preset extraction templates for common scenarios.
| Preset | Use Case |
| --------------------------- | ----------------------------- |
| **Candidate Overview** | General conversation summary |
| **Hard skill assessment** | Technical skills evaluation |
| **Per question assessment** | Question-by-question analysis |
| **Custom disposition** | Outcome classification |
| **Soft skill assessment** | Communication skills |
| **Logistical assessment** | Scheduling evaluation |
| **Eligibility assessment** | Qualification check |
| **call\_status** | Call outcome status |
Add **Custom Questions** to extend any preset with your own analysis criteria.
***
### Custom Analytics
Create custom post-call tasks to extract specific data points.
Open the custom analytics modal.
Define an identifier (e.g., `user_interested`).
Select: Freeflow, Numeric, List, Advanced List, or Advanced Boolean.
Describe what to extract (e.g., "Yield whether the user is interested").
Choose output format (String, etc.).
***
## Use Cases
Automatically update customer records after calls
Extract qualification data from sales calls
Capture required data points for regulations
Analyze conversation outcomes and metrics
***
## Next Steps
Configure inbound call settings
Add function tools and APIs
View call logs and transcripts
Learn about webhook events
# Configure Voice and Transcription Settings
Source: https://www.bolna.ai/docs/agent-setup/audio-tab
Set up speech-to-text and text-to-speech for Bolna Voice AI agents. Choose providers like Deepgram and ElevenLabs, and fine-tune voice quality.
## What is the Audio Tab?
The Audio Tab is where you configure how your agent listens and speaks. Set up language preferences, choose transcription providers for speech-to-text, and select voice synthesizers for natural-sounding responses.
***
## Configuration Options
### Configure Language
Set your agent's primary language and enable multilingual support.
Choose primary language (English, Hindi, Spanish, etc.)
Automatically detect and switch languages during calls
Enable **Auto Language Switch** for multilingual support. Your agent will detect the caller's language and respond accordingly.
***
### Speech-to-Text (Transcription)
Configure how your agent converts spoken words into text.
Choose your transcription provider (e.g., Deepgram, Azure).
Pick the model (e.g., `nova-3` for best accuracy).
Boost recognition of specific terms like names or brand words.
**Keywords help accuracy!** Add names, brand terms, or technical words with boost values. Format: `word:boost_value` (e.g., `Bruce:100`).
***
### Text-to-Speech (Voice)
Configure how your agent sounds with voice synthesis settings.
Choose your voice synthesis provider (e.g., ElevenLabs, Azure).
Pick the model (e.g., `eleven_turbo_v2_5` for low latency).
Select a specific voice. Click ▶️ to preview!
Click **"Add voices"** to import or clone custom voices for a unique brand experience.
***
### Voice Tuning
Fine-tune your agent's voice quality with these settings.
| Setting | Description | Recommended |
| ---------------------- | ------------------------------- | ------------------------------------ |
| **Buffer Size** | Audio buffering before playback | 200 (balance of quality and speed) |
| **Speed Rate** | Speaking speed | 1.0 (natural pace) |
| **Similarity Boost** | Voice matching accuracy | 0.75 (close to original voice) |
| **Stability** | Voice consistency | 0.5 (balanced expression) |
| **Style Exaggeration** | Voice characteristics | 0 (neutral, increase for expressive) |
**Balance is key!** High buffer size improves quality but increases latency. Test different settings to find the right balance for your use case.
***
## Next Steps
Configure prompts and welcome message
Configure transcription and latency
Create custom voice clones
Learn about transcription options
# Configure Telephony and Call Settings
Source: https://www.bolna.ai/docs/agent-setup/call-tab
Set up telephony providers, noise cancellation, voicemail detection, and call management for Bolna Voice AI. Configure timeouts and call restrictions.
## What is the Call Tab?
The Call Tab is where you configure how your agent handles phone calls. Set up your telephony provider, enable call features like noise cancellation and voicemail detection, and manage call timing and hangup behavior.
***
## Configuration Options
### Telephony Provider & Call Features
Configure your telephony provider and toggle powerful call capabilities.
Filter background noise for clearer calls (adjustable intensity)
Detect voicemail systems to avoid awkward messages
Accept touch-tone input for IVR-style menus
Automatically retry failed calls later
Connect your own telephony provider in [Providers](/getting-started/providers) for more control and cost savings.
***
### Final Call Message
Configure the last message your agent says before disconnecting.
Choose the language for your final message (supports multi-language).
Enter a warm, professional closing (e.g., "Thank you for your time. Goodbye!")
Click **+ Add** to include final messages in other languages.
A warm, professional final message leaves a positive lasting impression on callers.
***
### Call Management
Configure how and when calls should end.
| Setting | Description | Recommended |
| -------------------------- | -------------------------------------- | ------------------------------------------ |
| **Hangup on User Silence** | Auto-hangup after X seconds of silence | 6-10 seconds |
| **Total Call Timeout** | Maximum call duration in seconds | 300s (5 min) for support, higher for sales |
**Set reasonable timeouts** to manage costs and prevent stuck calls. Very long calls can indicate issues or abandoned calls.
***
### Outbound Call Timing Restrictions
**Compliance matters!** Many regions have laws restricting when you can make outbound calls. Enable timing restrictions to stay compliant with local regulations.
Toggle on to restrict outbound calls to specific time windows and avoid calling during prohibited hours.
***
## Next Steps
Add function tools and APIs
Configure latency and interruptions
Connect Twilio, Plivo, or Exotel
Set up inbound call routing
# Configure Voice AI Latency and Interruptions
Source: https://www.bolna.ai/docs/agent-setup/engine-tab
Fine-tune your Bolna Voice AI agent's performance. Configure transcription accuracy, interruption thresholds, response latency, and user detection.
## What is the Engine Tab?
The Engine Tab controls the core performance settings of your voice AI agent. Fine-tune transcription accuracy, interruption behavior, response timing, and user presence detection for optimal conversation quality.
***
## Configuration Options
### Transcription & Interruptions
Control how speech is captured and processed during conversations.
Enable for higher accuracy transcription. Essential for compliance and call analytics.
Number of words to wait before considering user input as an interruption.
**Stopwords like "Stop", "Wait", "Hold On"** will always pause the agent immediately, regardless of the interruption threshold.
***
### Response Latency
Configure how quickly your agent responds to user input.
| Setting | Description | Impact |
| --------------------- | ------------------------------------ | ----------------------------------- |
| **Response Rate** | Choose preset or Custom | Balanced, Fast, or Custom timing |
| **Endpointing (ms)** | Wait time before generating response | Lower = faster but may cut off user |
| **Linear Delay (ms)** | Accounts for mid-sentence pauses | Prevents premature responses |
**Lower latency isn't always better!** Setting values too low may cause the agent to interrupt users mid-sentence. Start with defaults and adjust based on testing.
For **natural conversations**, use Endpointing around 200-300ms and Linear Delay around 400-500ms.
***
### User Online Detection
Detect when users go silent and automatically re-engage them.
Toggle **User Online Detection** to check if the user is still on the call.
Customize the prompt (e.g., "Hey, are you still there?") with multi-language support.
Set **Invoke message after (seconds)** to control when the check triggers.
Set the timer between **8-15 seconds** to give users enough time to respond without seeming impatient.
***
## Best Practices
Use default settings initially and adjust based on real call feedback
Make test calls to experience the timing and interruption handling
Customer support may need longer pauses; sales may prefer faster responses
Review call recordings to identify timing issues
***
## Next Steps
Configure telephony and call features
Set up voice and transcription providers
Configure language model settings
Review call logs and recordings
# Set Up Inbound Calls & Caller Matching
Source: https://www.bolna.ai/docs/agent-setup/inbound-tab
Configure inbound call settings for Bolna Voice AI. Match callers using CSV, Google Sheets, or API. Set up spam prevention and preload customer data.
## What is the Inbound Tab?
The Inbound Tab is where you configure settings for receiving incoming calls. Match callers to your database, preload user data before the call starts, and set up spam prevention to protect your agents from abuse.
***
## Database for Inbound Phone Numbers
Match incoming calls to users and preload their data before the call starts. Choose from three data source options:
Connect your own API to fetch user data dynamically when a call comes in.
Choose **"Use your internal APIs"** from the dropdown.
Provide your API endpoint that will receive the caller data request.
Enter your Bearer token for secure authentication.
### Query Parameters
Bolna automatically passes these parameters to your API:
| Parameter | Description |
| ---------------- | ------------------------------- |
| `contact_number` | The caller's phone number |
| `agent_id` | Your agent's identifier |
| `execution_id` | Unique identifier for this call |
**Your API must return a JSON response** with user details. Bolna will inject this data directly into your agent's prompt for personalized conversations.
### Example API Request
```bash theme={"system"}
curl -X GET "https://your-api.com/user-data?contact_number=+919876543210&agent_id=abc123&execution_id=xyz789" \
-H "Authorization: Bearer YOUR_AUTH_TOKEN" \
-H "Content-Type: application/json"
```
### Example API Response
```json theme={"system"}
{
"user_name": "John Doe",
"account_status": "premium",
"last_purchase": "2026-01-15"
}
```
Authentication uses Bearer token and is stored securely by Bolna.
Upload a CSV file containing your user database.
Choose **"Use a CSV"** from the dropdown.
Click **Upload CSV File** and select your file.
The CSV file **must include a `contact_number` column** containing phone numbers. These numbers will be matched against the caller's phone number.
### CSV Format Example
```csv theme={"system"}
contact_number,user_name,account_type
+919876543210,John Doe,premium
+918765432109,Jane Smith,basic
```
Connect a public Google Sheet as your user database.
Choose **"Use a public Google Sheet"** from the dropdown.
Paste the URL of your public Google Sheet.
Specify the exact name of the sheet tab to use.
The sheet **must be public** and should include a `contact_number` column containing phone numbers.
***
## Call Restrictions
Toggle on **"Allow Calls Only from Database"** to restrict incoming calls to only phone numbers found in your chosen database. Unknown callers will be rejected.
***
## Spam Prevention Settings
Protect your agent from spam and abuse.
| Setting | Description |
| ---------------------------------- | ------------------------------------------------------------ |
| **Maximum Calls per Phone Number** | Limit calls from a single number. Set to `-1` for unlimited. |
| **Always-Allow List** | Phone numbers that bypass all call limits. |
Add your support team and VIP customers to the Always-Allow List to ensure they're never blocked.
***
## Use Cases
Only allow calls from registered customers
Preload customer data for personalized service
Limit repeated calls from the same number
Fetch real-time customer data via API
***
## Next Steps
Configure prompts and welcome message
Set up telephony and call management
Complete inbound setup guide
Purchase and manage phone numbers
# Choose and Configure LLM Models for Voice AI
Source: https://www.bolna.ai/docs/agent-setup/llm-tab
Select and configure the language model for your Bolna Voice AI agent. Choose from OpenAI, Azure, Anthropic, connect knowledge bases, and set up guardrails.
## What is the LLM Tab?
The LLM Tab is where you select and configure the intelligence behind your voice AI agent. Choose your language model provider, adjust response parameters, and connect knowledge bases for enhanced conversations.
***
## Configuration Options
### Choose LLM Model
Select your AI provider and model for conversation intelligence.
Choose from Azure, OpenAI, Anthropic, Groq, and more
Pick the specific model (e.g., `gpt-4.1-mini cluster`)
Connect your own provider keys in [Providers](/getting-started/providers) to reduce costs and access more models.
***
### Model Parameters
Fine-tune how your agent generates responses.
| Parameter | Description | Recommended |
| -------------------- | ------------------------------ | ------------------------------ |
| **Tokens Generated** | Max tokens per LLM output | 300-500 for concise responses |
| **Temperature** | Controls creativity/randomness | 0.3-0.5 for balanced responses |
**Keep temperature low** (0.3-0.5) if you want consistent, controlled responses. Higher temperature increases creativity but may cause deviation from your prompt instructions.
***
### Add Knowledge Base
Connect your knowledge bases to give your agent accurate, contextual information.
Open the **"Select knowledge bases"** multi-select dropdown.
Check one or more knowledge bases (PDFs, URLs) to connect.
Click **"Add new knowledgebase"** to create and upload new content.
Knowledge bases enable your agent to answer questions with accurate, up-to-date information from your documents and URLs. Connect multiple knowledge bases for comprehensive coverage.
Create knowledge bases in the [Knowledge Base](/getting-started/knowledge-base) section by uploading PDFs or adding URLs.
***
### Add FAQs & Guardrails
Create structured responses and safety controls for your agent.
Pre-defined answers to common questions that bypass LLM generation for faster, consistent responses
Safety rules that control inappropriate content and maintain professional boundaries
Click **"Add a new block for FAQs & Guardrails"** to open the configuration modal:
Give a descriptive name (e.g., "Pricing Questions", "Off-Topic Deflection").
Define the forced response when this rule triggers.
Set matching sensitivity (0.9 = strict, lower = more matches but may trigger unintentionally).
Add up to 20 example phrases that should trigger this response.
**Lower thresholds** increase matching likelihood but may cause false triggers. Start with 0.8-0.9 and adjust based on testing.
**[Learn more about Guardrails →](/guardrails)** to understand how to maintain professionalism, ensure compliance, and protect your brand during AI conversations.
***
## Next Steps
Create and manage knowledge bases
Learn guardrails best practices
Configure prompts and welcome message
Connect your own LLM provider
# Configure Voice AI Agents in Bolna
Source: https://www.bolna.ai/docs/agent-setup/overview
Complete guide to configuring Bolna Voice AI agents. Customize prompts, test conversations, and deploy agents for inbound and outbound calls.
## What is Agent Setup?
Agent Setup is where you configure and fine-tune your Voice AI agents. Access it from the [Bolna Platform](https://platform.bolna.ai/) after creating or selecting an agent.
***
## Your Agents Sidebar
The left sidebar shows all your agents and provides quick access to create or import agents.
| Action | Description |
| --------------- | ------------------------------------------------------------------------------ |
| **+ New Agent** | Create a new agent using Auto Build, Pre-built templates, or from scratch |
| **Import** | Import an existing agent configuration using an [agent ID](/copy-import-agent) |
| **Search** | Quickly find agents by name |
| **Agent List** | Click any agent to open its configuration |
New agents are created in **draft** status until you save them.
***
## Agent Header
The header bar displays key information and quick actions for your selected agent.
| Element | Description |
| ------------------- | -------------------------------------------------------- |
| **Agent Name** | Your agent's display name |
| **Agent ID** | Copy for API integrations |
| **Share** | Generate a shareable link for team collaboration |
| **Cost per min** | Estimated cost breakdown per minute |
| **Routing** | Active routing region (e.g., India routing) |
| **Provider Status** | Status indicators for Transcriber, LLM, Voice, Telephony |
Receive a test call on your phone number
Configure this agent for inbound calls
***
## Configuration Tabs
Configure every aspect of your agent using the **8 specialized tabs**.
Prompts & welcome message
Model & knowledge base
Voice & transcription
Latency & interruptions
Telephony & voicemail
Functions & APIs
Webhooks & extraction
Caller matching
***
## Testing & Saving
Test your agent before deploying and save your changes.
### Testing Options
| Method | Description | Best For |
| ----------------------- | ------------------------------------- | ------------------------------------ |
| **Chat with agent** | Text-based conversation testing | Quick prompt iteration and debugging |
| **Get call from agent** | Receive a test call on your phone | Real-world voice experience |
| **Test via browser** | Make calls directly from your browser | Testing without using phone minutes |
**Pro tip:** Use "Chat with agent" for quick iterations, then validate with a real phone call before deploying!
### Save & Manage
| Action | Description |
| --------------------- | ------------------------------------------------------------------------------- |
| **Save agent** | Save your configuration — changes only take effect after saving! |
| **See all call logs** | View [call history](/getting-started/call-history), recordings, and transcripts |
| **Delete** | Remove the agent (use with caution) |
**Remember to save!** Your changes won't apply until you click **Save agent**.
***
## Quick Links
Step-by-step guide to creating your first agent
Import existing agent configurations
Purchase phone numbers for inbound calls
View call logs, recordings, and transcripts
***
## Next Steps
Configure prompts and welcome message
Choose your language model and knowledge base
Set up voice and transcription
Upload documents for context-aware responses
# Function Tools and API Integrations
Source: https://www.bolna.ai/docs/agent-setup/tools-tab
Connect external APIs and function tools to your Bolna Voice AI agent. Enable CRM lookups, Cal.com booking, call transfers, and custom integrations.
## What is the Tools Tab?
The Tools Tab is where you connect external tools and APIs that your language model can call during conversations. This allows the LLM to retrieve real-time data, perform calculations, or trigger actions dynamically.
***
## Configuration Options
### Choose Functions
Select from pre-built functions or create your own custom tools.
Check available slots using Cal.com integration
Book appointments directly using Cal.com
Route calls to human agents or other numbers
Add your own custom API integrations
Check out **[Examples & Docs](/tool-calling/custom-function-calls)** for function tool templates and implementation guides.
***
### Add Transfer Call
**Transfer Call** enables routing calls to human agents or other phone numbers during a conversation. Essential for escalation scenarios where AI needs to hand off to a human.
Click **"Add Transfer Call"** to configure call transfer. Learn more in the [Tool Calling Guide](/tool-calling/introduction).
***
### Managing Tools
Once you add functions, they appear as configurable tool cards:
| Element | Description |
| -------------------- | ----------------------------------------------------------------- |
| **Tool Name** | Identifier for the function (e.g., `check_availability_of_slots`) |
| **Configure Button** | Click to set up the tool's parameters and API connection |
| **Delete Button** | Remove the tool from your agent |
***
## Use Cases
Look up customer data during calls
Schedule appointments in real-time with Cal.com
Check order information from your database
Trigger payment flows securely
Query external knowledge bases
Route to human agents when needed
***
## Next Steps
Learn about function tools and call transfer
Create your own function tools
Configure webhooks and post-call tasks
Configure inbound call settings
# Agents Library
Source: https://www.bolna.ai/docs/agents-library
Browse Bolna's Voice AI agent templates for quick and efficient setup. Customize pre-built agents to create powerful, AI-driven voice agents seamlessly.
## What is the Agents Library?
The Bolna Agents Library provides ready-to-use Voice AI agent templates that you can import and customize for your specific use case. Each template comes pre-configured with optimized prompts, workflows, and settings, allowing you to deploy production-ready agents in minutes rather than hours.
## How to use agent templates?
1. Click the "Import this agent →" link for any template below
2. The agent will be imported into your [Playground](/playground/agent-setup)
3. Customize the prompts, [context variables](/using-context), and settings to match your needs
4. Test using the Playground chat or by [making test calls](/making-outgoing-calls)
5. Deploy for [inbound](/receiving-incoming-calls) or [outbound](/making-outgoing-calls) calling
## Featured agents
AI agents that screen, interview, and onboard candidates at scale
Languages: `English`
Import this agent →
Provides 24/7 inbound call answering for FAQs and customer triage
Languages: `English`
Import this agent →
Calls customers with abandoned items in carts, recovering sales
Languages: `English + Hindi`
Import this agent →
Calls every lead to ask qualifying questions, answer FAQs, and warmly introduce the business
Languages: `Hindi`
Import this agent →
Conducts personalized guidance calls to warmly onboard users
Languages: `English`
Import this agent →
Answers every call to handle clinic, hotel, and office scheduling
Languages: `English`
Import this agent →
## Additional agent templates
| Agent name | Learn More | Import Agent | Description |
| ------------------------------------------------------------------ | -------------------------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| [COD Confirmation Agent](/voice-agents/cod-confirmation-agent) | [Details →](/voice-agents/cod-confirmation-agent) | [Import →](https://bolna.ai/a/42a04bee-a4e9-442c-bf85-c6e6064ad976) | Handles a variety of last mile logistics tasks, saving human effort |
| [Announcements Agent](/voice-agents/announcements-agent) | [Details →](/voice-agents/announcements-agent) | [Import →](https://bolna.ai/a/09344ad0-0991-440b-89ff-51ba4fe7d7b1) | Keeps users engaged with all feature upgrades and product launches |
| [Reminders Agent](/voice-agents/reminders-agent) | [Details →](/voice-agents/reminders-agent) | [Import →](https://bolna.ai/a/88bb2f3c-cfc0-4f3d-b0a2-6ac962ba9737) | Automates all reminders, from EMIs and collections to form filling deadlines |
| [Surveys Agent](/voice-agents/surveys-agent) | [Details →](/voice-agents/surveys-agent) | [Import →](https://bolna.ai/a/e3f31313-c28c-452e-9026-70edd7042691) | Automated NPS, feedback & product surveys with detailed personalised questioning |
| [Property Tech Agent](/voice-agents/property-tech-agent) | [Details →](/voice-agents/property-tech-agent) | [Import →](https://bolna.ai/a/d3dbc421-b964-4c12-8afa-e087e440cb3e) | Lead Qualification of Owner or Broker and asks further details about property |
| [Customer Support Agent](/voice-agents/customer-support-agent) | [Details →](/voice-agents/customer-support-agent) | [Import →](https://bolna.ai/a/4f0d937f-3d07-479b-9352-9f3271285d8a) | Demo support agent (English + Hindi) ; Handles order queries, tracking, and product issues empathetically |
| [Salon Booking Agent](/voice-agents/salon-booking-agent) | [Details →](/voice-agents/salon-booking-agent) | [Import →](https://bolna.ai/a/547e8f2d-d231-4fc6-a9f1-b90801d672b8) | Front Desk for Salon ; Schedules appointment and collects information |
| [Weekend Planner Agent](/voice-agents/weekend-planner-agent) | [Details →](/voice-agents/weekend-planner-agent) | [Import →](https://bolna.ai/a/00b05a0f-d451-4afe-b55f-7e2a3fa4896d) | Plan your weekend with Samantha ; Helps users make weekend and vacation plans |
| [Sales - Credit Card Agent](/voice-agents/sales-credit-card-agent) | [Details →](/voice-agents/sales-credit-card-agent) | [Import →](https://bolna.ai/a/68762ade-7e39-4b06-96e6-0d98863fbd0b) | Sales agent for credit cards (Hindi) ; Helps fintech companies sell credit cards |
| [Sales - Loans Agent](/voice-agents/sales-loans-agent) | [Details →](/voice-agents/sales-loans-agent) | [Import →](https://bolna.ai/a/29780b7b-876e-40a6-96bd-069b8409dedb) | Sales agent for Loans (Hindi) ; Helps fintech companies sell loans |
# Create Voice AI Agent API (deprecated)
Source: https://www.bolna.ai/docs/api-reference/agent/create
POST /agent
Learn how to create new agents with Bolna APIs, enabling customized tasks, prompts, and configurations for Bolna voice AI agents.
These APIs have now been deprecated.
Please use the latest [**v2 APIs**](/api-reference/agent/v2/overview).
# Retrieve Voice AI Agent Details API (deprecated)
Source: https://www.bolna.ai/docs/api-reference/agent/get
GET /agent/{agent_id}
Retrieve detailed Voice AI agent information, including configuration, status, and tasks, using Bolna APIs.
These APIs have now been deprecated.
Please use the latest [**v2 APIs**](/api-reference/agent/v2/overview).
# List all Voice AI Agents API (deprecated)
Source: https://www.bolna.ai/docs/api-reference/agent/get_all
GET /agent/all
List all Voice AI agents under your account, along with their names, statuses, and creation dates, using Bolna APIs.
These APIs have now been deprecated.
Please use the latest [**v2 APIs**](/api-reference/agent/v2/overview).
# Get All Voice AI Agent Executions API
Source: https://www.bolna.ai/docs/api-reference/agent/get_all_agent_executions
GET /agent/{agent_id}/executions
Access all execution records for a specific agent, providing insights into performance and past interactions with Bolna APIs.
# Bolna Voice AI Agent APIs Overview (deprecated)
Source: https://www.bolna.ai/docs/api-reference/agent/overview
Explore Bolna Voice AI Agent APIs overview, featuring endpoints for creating, managing, and executing autonomous voice agents.
These APIs have now been deprecated.
Please use the latest [**v2 APIs**](/api-reference/agent/v2/overview).
## Endpoints
```
POST /agent
GET /agent
PUT /agent/:agent_id
PATCH /agent/:agent_id
GET /agent/all
```
## Agent Object Attributes
### `agent_config`
* `agent_name` *string* **(required)**
Name of the agent
* `agent_welcome_message` *string* **(required)**
Initial agent welcome message. you can pass dynamic values here using variables encloed within `{}`
* `webhook_url` *string* **(required)**
Get real-time details of the call progress and call data on a webhook. All supported events are listed in [Poll call data using webhooks](/polling-call-status-webhooks)
* `tasks` *array* **(required)**
Definitions and configuration for the agentic tasks
### `agent_prompts`
Prompts to be provided to the agent.
# Patch Update to Voice AI Agent API (deprecated)
Source: https://www.bolna.ai/docs/api-reference/agent/patch_update
PATCH /agent/{agent_id}
Learn how to partially update properties. Update Bolna Voice AI agent name, welcome message, webhook URL, voice settings, and prompts, using this endpoint.
These APIs have now been deprecated.
Please use the latest [**v2 APIs**](/api-reference/agent/v2/overview).
# Update Voice AI Agent API (deprecated)
Source: https://www.bolna.ai/docs/api-reference/agent/update
PUT /agent/{agent_id}
Update agent configurations, tasks, and prompts to refine behavior and capabilities using Bolna Voice AI agent APIs.
These APIs have now been deprecated.
Please use the latest [**v2 APIs**](/api-reference/agent/v2/overview).
# Create Voice AI Agent API
Source: https://www.bolna.ai/docs/api-reference/agent/v2/create
POST /v2/agent
Learn how to create new agents with Bolna APIs, enabling customized tasks, prompts, and configurations for Bolna voice AI agents.
# Delete Voice AI Agent API
Source: https://www.bolna.ai/docs/api-reference/agent/v2/delete
DELETE /v2/agent/{agent_id}
Use Bolna APIs to delete agents and their related data, ensuring proper cleanup of batches, executions, and configurations.
This deletes **ALL** agent data including all batches, all executions, etc.
# Retrieve Voice AI Agent Details API
Source: https://www.bolna.ai/docs/api-reference/agent/v2/get
GET /v2/agent/{agent_id}
Retrieve detailed Voice AI agent information, including configuration, status, and tasks, using Bolna APIs.
# Retrieve Voice AI Agent Execution API
Source: https://www.bolna.ai/docs/api-reference/agent/v2/get_agent_execution
GET /agent/{agent_id}/execution/{execution_id}
Fetch specific execution details of a Voice AI agent, including conversation times, statuses, and metrics, via Bolna APIs.
# List all Voice AI Agents API
Source: https://www.bolna.ai/docs/api-reference/agent/v2/get_all
GET /v2/agent/all
List all Voice AI agents under your account, along with their names, statuses, and creation dates, using Bolna APIs.
# Get All Voice AI Agent Executions API
Source: https://www.bolna.ai/docs/api-reference/agent/v2/get_all_agent_executions
GET /v2/agent/{agent_id}/executions
Access all execution records for a specific agent, providing insights into performance and past interactions with Bolna APIs.
## Pagination
This API supports pagination using the `page_number` and `page_size` query parameters. You can utilize `has_more` in the API response to determine if you should fetch the next page. You can learn more about it from the [pagination documentation](/api-reference/pagination).
# Bolna Voice AI Agent APIs Overview
Source: https://www.bolna.ai/docs/api-reference/agent/v2/overview
Explore Bolna Voice AI Agent APIs overview, featuring endpoints for creating, managing, and executing autonomous voice agents.
## Endpoints
```
POST /v2/agent
GET /v2/agent
PUT /v2/agent/:agent_id
GET /v2/agent/all
```
## Agent Object Attributes
### `agent_config`
* `agent_name` *string* **(required)**
Name of the agent
* `agent_welcome_message` *string* **(required)**
Initial agent welcome message. you can pass dynamic values here using variables encloed within `{}`
* `webhook_url` *string* **(required)**
Get real-time details of the call progress and call data on a webhook. All supported events are listed in [Poll call data using webhooks](/polling-call-status-webhooks)
* `tasks` *array* **(required)**
Definitions and configuration for the agentic tasks
### `agent_prompts`
Prompts to be provided to the agent.
# Patch Update to Voice AI Agent API
Source: https://www.bolna.ai/docs/api-reference/agent/v2/patch_update
PATCH /v2/agent/{agent_id}
Learn how to partially update properties. Update Bolna Voice AI agent name, welcome message, webhook URL, voice settings, and prompts, using this endpoint.
Currently, only the following agent attributes can be updated for the `PATCH` update.
* `agent_name`
* `agent_welcome_message`
* `webhook_url`
* `synthesizer`
* `agent_prompts`
* `ingest_source_config`
# Stop Agent Queued Calls API
Source: https://www.bolna.ai/docs/api-reference/agent/v2/stop
POST /v2/agent/{agent_id}/stop
Use Bolna APIs to stop all queued calls for a specific agent, preventing any pending calls from being executed.
This stops **ALL** the queued calls for a given agent.
This endpoint stops all queued calls for the specified agent. Any calls that are currently in the queue waiting to be executed will be cancelled and will not be processed.
# Update Voice AI Agent API
Source: https://www.bolna.ai/docs/api-reference/agent/v2/update
PUT /v2/agent/{agent_id}
Update agent configurations, tasks, and prompts to refine behavior and capabilities using Bolna Voice AI agent APIs.
# Create Batch API
Source: https://www.bolna.ai/docs/api-reference/batches/create
POST /batches
Discover how to create a batch for Bolna Voice AI agent by uploading a CSV file containing user contact numbers and prompt variable details for users.
# Delete Batch API
Source: https://www.bolna.ai/docs/api-reference/batches/delete
DELETE /batches/{batch_id}
Understand how to delete a specific batch using its ID, effectively removing it from your scheduled or active batches.
# List Batch Executions API
Source: https://www.bolna.ai/docs/api-reference/batches/executions
GET /batches/{batch_id}/executions
Learn how to retrieve all executions from a batch, providing detailed information on each call's outcome and metrics.
# Get Batch API
Source: https://www.bolna.ai/docs/api-reference/batches/get_batch
GET /batches/{batch_id}
Find out how to retrieve details of a specific batch, including its creation time, status, call status and scheduled execution time.
# List All Batches API
Source: https://www.bolna.ai/docs/api-reference/batches/get_batches
GET /batches/{agent_id}/all
Explore how to list all batches associated with a particular Bolna Voice AI agent, providing an overview of their statuses, schedules and other relevant details
# Batch APIs Overview
Source: https://www.bolna.ai/docs/api-reference/batches/overview
Understand how to create and schedule multiple Bolna Voice AI calls together using Bolna Batch APIs for efficient call management.
## Endpoints
```
POST /batches
POST /batches/schedule
POST /batches/:batch_id/stop
GET /batches/:batch_id
GET /batches/:batch_id/executions
GET /batches/:agent_id
DELETE /batches/:batch_id
```
# Schedule Batch API
Source: https://www.bolna.ai/docs/api-reference/batches/schedule
POST /batches/{batch_id}/schedule
Learn how to schedule a batch for calling via Bolna Voice AI agent by specifying the batch ID and the desired execution time.
# Stop Batch API
Source: https://www.bolna.ai/docs/api-reference/batches/stop
POST /batches/{batch_id}/stop
Understand how to stop a running batch using its ID, allowing you to halt ongoing calls in the batch.
# Make Voice AI Call API
Source: https://www.bolna.ai/docs/api-reference/calls/make
POST /call
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.
# Calling APIs overview
Source: https://www.bolna.ai/docs/api-reference/calls/overview
Explore Bolna Calling APIs to invoke outbound Voice AI phone calls from your agents. This overview provides the available endpoints and their functionalities.
## Endpoints
```
POST /call
```
# Stop a Previously Initiated Voice AI Call API
Source: https://www.bolna.ai/docs/api-reference/calls/stop_call
POST /call/{execution_id}/stop
Learn how to stop a call when its status is `queued` or `scheduled` This API allows you to cancel pending calls before they are executed.
# Get Batch Executions API
Source: https://www.bolna.ai/docs/api-reference/executions/get_batch_executions
GET /batches/{batch_id}/executions
Retrieve all executions for specific batches using Bolna APIs. This endpoint provides detailed information on each call's outcome and metrics within the batch.
# Retrieve Voice AI Execution API
Source: https://www.bolna.ai/docs/api-reference/executions/get_execution
GET /executions/{execution_id}
Fetch details of a specific phone call execution by its ID using Bolna APIs. This includes information such as conversation time, status, and telephony data.
# Retrieve Voice AI Execution Raw Logs API
Source: https://www.bolna.ai/docs/api-reference/executions/get_execution_raw_logs
GET /executions/{execution_id}/log
Fetch raw logs of a specific phone call execution by its ID using Bolna APIs. This includes information such as prompts, requests & responses by the models
# Get All Voice AI Agent Executions API
Source: https://www.bolna.ai/docs/api-reference/executions/get_executions
GET /v2/agent/{agent_id}/executions
Retrieve all executions performed by a specific agent using Bolna APIs. This endpoint provides a comprehensive history of the agent's calls and conversations.
## Pagination
This API supports pagination using the `page_number` and `page_size` query parameters. You can utilize `has_more` in the API response to determine if you should fetch the next page. You can learn more about it from the [pagination documentation](/api-reference/pagination).
# Executions APIs overview
Source: https://www.bolna.ai/docs/api-reference/executions/overview
Access your Voice AI agents call and conversation history using Bolna Executions APIs. This page details the available endpoints for managing call executions.
## Endpoints
```
GET /executions/:execution_id
GET /batch/:batch_id/executions
GET /v2/agent/:agent_id/executions
GET /executions/:execution_id/log
```
# Set Inbound Agent API
Source: https://www.bolna.ai/docs/api-reference/inbound/agent
POST /inbound/setup
Configure Bolna Voice AI agent to handle inbound calls automatically by associating it with a specific phone number using Bolna APIs.
# Inbound Bolna Voice AI Agent APIs Overview
Source: https://www.bolna.ai/docs/api-reference/inbound/overview
Discover how to set up Bolna Voice AI agents to answer inbound calls, enabling responsive communication channels.
## Endpoints
```
POST /inbound/setup
```
# Remove Inbound Agent API
Source: https://www.bolna.ai/docs/api-reference/inbound/unlink
POST /inbound/unlink
Remove and unlink a Bolna Voice AI agent from a specific phone number to disable automated inbound voice call answering by AI agents.
# Bolna API Documentation
Source: https://www.bolna.ai/docs/api-reference/introduction
Use and leverage Bolna Voice AI using APIs through HTTP requests from any language in your applications and workflows.
## What is the Bolna API?
The Bolna API enables you to programmatically create, configure, and manage Voice AI agents from your applications. Build voice AI capabilities into your products using simple HTTP requests from any programming language.
Bolna API features consistent, resource-oriented URLs, handles application/json request bodies, returns responses in JSON format, and utilizes standard HTTP response codes, authentication methods, and HTTP verbs.
You must have a valid Bolna account to generate and use APIs
## How do I authenticate with the Bolna API?
* Login to the dashboard at [https://platform.bolna.ai](https://platform.bolna.ai)
* Navigate to [Developers](https://platform.bolna.ai/developers) tab from the left menu bar after login
* Click the button `Generate a new API Key` to generate a key
* Save your API Key
The API Key will be shown only once. Hence, please save it somewhere secure.
## Using the API Key
To authenticate your API requests, you must include your `API Key` in the Authorization header of HTTP requests made as a `Bearer` token
```
Authorization: Bearer
```
## Example of an Authenticated API Request
Following is an example of making a GET request to Bolna API using the API key:
```http theme={"system"}
GET https://api.bolna.ai/agent/all
Headers:
Authorization: Bearer
```
## Next steps
Ready to integrate Bolna into your application? Explore the API endpoints:
* [Create an agent](/api-reference/agent/create) programmatically
* [Make outbound calls](/api-reference/calls/make) from your application
* [Get execution details](/api-reference/executions/get_execution) to retrieve call results
* Review [agent configuration options](/playground/agent-setup) to understand available parameters
For advanced integrations, explore [custom function calls](/tool-calling/custom-function-calls) and [webhook configuration](/playground/tasks-tab).
# Create Knowledgebase API
Source: https://www.bolna.ai/docs/api-reference/knowledgebase/create
POST /knowledgebase
Upload a PDF document or provide a URL to create a knowledgebase, enhancing your Bolna Voice AI agent's information base and response accuracy.
# Delete Knowledgebase API
Source: https://www.bolna.ai/docs/api-reference/knowledgebase/delete
DELETE /knowledgebase/{rag_id}
Remove and delete an existing knowledgebase from your Bolna account maintaining your Bolna Voice AI agents upto date.
# Get Knowledgebase API
Source: https://www.bolna.ai/docs/api-reference/knowledgebase/get_knowledgebase
GET /knowledgebase/{rag_id}
Retrieve details of a specific knowledgebase, including its ID, file name, creation time, and status, using Bolna APIs.
# List All Knowledgebases API
Source: https://www.bolna.ai/docs/api-reference/knowledgebase/get_knowledgebases
GET /knowledgebase/all
Retrieve all knowledgebases associated with your account, including their status and creation dates.
# Knowledgebases Overview
Source: https://www.bolna.ai/docs/api-reference/knowledgebase/overview
Learn how to ingest PDFs and URLs as knowledgebases for your Bolna Voice AI agents. Agents can use multiple knowledgebases simultaneously.
## Endpoints
```
POST /knowledgebase
GET /knowledgebase/:rag_id
GET /knowledgebase/all
DELETE /knowledgebase/:rag_id
```
# Pagination in Bolna API
Source: https://www.bolna.ai/docs/api-reference/pagination
Learn how to use pagination in Bolna Voice AI APIs using `page_number` and `page_size` to fetch results efficiently and build scalable workflows.
The endpoints also support pagination using the `page_number` and `page_size` query parameters. This allows you to fetch large sets of results in smaller, manageable chunks.
## Query Parameters
* `page_number` (integer, optional): The page of results to retrieve. Defaults to `1`. The first page starts at `1`.
* `page_size` (integer, optional): The number of results per page. Defaults to `20`. You can request up to `50` results per page.
## How it works
The API uses offset-based pagination under the hood. For example:
| page\_number | page\_size | Returned records |
| ------------ | ---------- | ---------------- |
| 1 | 10 | Records 1–10 |
| 2 | 10 | Records 11–20 |
| 3 | 5 | Records 11–15 |
## Example Request
```curl example-request theme={"system"}
GET /v2/agent/1234/executions?page_number=2&page_size=5
```
```json example-response theme={"system"}
{
"total": 38,
"page": 2,
"page_size": 5,
"has_more": true,
"data": [
{ "id": "ex_101", "status": "success", "created_at": "..." },
{ "id": "ex_102", "status": "failed", "created_at": "..." },
...
]
}
```
## Tips
* Use `has_more` to determine if you should fetch the next page.
* Combine pagination with filters supported in the API to narrow results efficiently.
# Buy Phone Numbers API
Source: https://www.bolna.ai/docs/api-reference/phone-numbers/buy
POST /phone-numbers/buy
Buy virtual phone numbers with full purchase, pricing, and provider details to use with Bolna Voice agents for outbound and inbound calls.
# Delete Phone Numbers API
Source: https://www.bolna.ai/docs/api-reference/phone-numbers/delete
DELETE /phone-numbers/{phone_number_id}
Delete a purchased phone number to stop billing and remove it permanently from your active inventory.
# List Phone Numbers API
Source: https://www.bolna.ai/docs/api-reference/phone-numbers/get_all
GET /phone-numbers/all
Retrieve all phone numbers associated with your account, including details like creation date and telephony provider like Twilio, Plivo, etc.
# Phone Numbers APIs Overview
Source: https://www.bolna.ai/docs/api-reference/phone-numbers/overview
Manage your phone numbers effectively using Bolna APIs, including buying, listing, deleting and associating numbers with Bolna Voice AI agents.
## Endpoints
```
POST /phone-numbers/all
GET /phone-numbers/search
POST /phone-numbers/buy
DELETE /phone-numbers/delete
```
# Search Phone Numbers API
Source: https://www.bolna.ai/docs/api-reference/phone-numbers/search
GET /phone-numbers/search
Search available phone numbers by region, locality, or pattern, with price to use them with Bolna Voice agents.
# Add a New Provider API
Source: https://www.bolna.ai/docs/api-reference/providers/add
POST /providers
Learn how to securely add a new provider to your Bolna account by specifying the provider's name and associated credentials.
You can add your own providers securely in Bolna. Please [read this page](/providers) for more information about all current supported providers.
# List Providers API
Source: https://www.bolna.ai/docs/api-reference/providers/get
GET /providers
Retrieve all providers associated with your Bolna account, including their IDs, names, and creation timestamps.
# Providers APIs overview
Source: https://www.bolna.ai/docs/api-reference/providers/overview
Add and manage your own providers securely in Bolna, supporting various telephony and voice services.
You can add your own providers securely in Bolna.
Please [read this page](/providers) for more information about all current supported providers.
## Endpoints
```
POST /providers
GET /providers
DELETE /providers/:provider_key_name
```
# Remove a Provider API
Source: https://www.bolna.ai/docs/api-reference/providers/remove
DELETE /providers/{provider_key_name}
Delete a previously added provider from your Bolna account, ensuring your integrations remain current.
# Rate Limiting
Source: https://www.bolna.ai/docs/api-reference/rate-limiting
Understand the API rate limits applied to Bolna API endpoints to ensure fair usage and platform stability.
All Bolna API endpoints are subject to rate limiting to ensure fair usage and maintain platform stability. Rate limits are applied per **organization** (if the user belongs to one) or per **user** otherwise.
## Rate Limits
### Endpoint-Specific Limits
The following endpoints have specific rate limits:
| Endpoint | Rate Limit |
| --------------------------------- | ------------------- |
| `/v2/agent/{agent_id}/executions` | 500 requests/minute |
| `/v2/agent/{agent_id}` | 500 requests/minute |
| `/call` | 500 requests/minute |
### Default Limit
All other API endpoints are subject to a default rate limit of **1000 requests per minute**.
## How Rate Limits Are Applied
* If your account is part of an **organization**, the rate limit is shared across all users within that organization.
* If your account is **not** part of an organization, the rate limit applies to your individual user account.
## Exceeding the Rate Limit
If you exceed the rate limit for an endpoint, the API will return an **HTTP 429 (Too Many Requests)** response. When this happens:
* Wait before retrying the request.
* Implement exponential backoff in your application to gracefully handle rate limit responses.
## Best Practices
* **Cache responses** where possible to reduce the number of API calls.
* **Use webhooks** instead of polling for call status updates to minimize requests to execution endpoints.
* **Spread requests** evenly over time rather than sending them in bursts.
* **Monitor your usage** and implement client-side rate limiting to stay within the allowed limits.
# Get All Sub-Accounts Usage API
Source: https://www.bolna.ai/docs/api-reference/sub-accounts/all_usage
GET /sub-accounts/all/usage
Retrieve usage, consumption, and billing details for all sub-accounts under the authenticated organization.
This is an `enterprise` feature.
You can read more about our enterprise offering here [Bolna enterprise](/enterprise/plan).
## Summary
This endpoint returns aggregated usage data for **all sub-accounts** associated with the authenticated user's organization.\
It provides fine-grained insight into usage, consumption, and cost breakdowns for each sub-account.
## Endpoint
```yaml theme={"system"}
GET /sub-accounts/all/usage
```
# Create a new Sub-Account API
Source: https://www.bolna.ai/docs/api-reference/sub-accounts/create
POST /sub-accounts/create
Create a new sub-account using the Bolna API to define separate workspaces with custom configurations for enterprise-level management.
This is an `enterprise` feature.
You can read more about our enterprise offering here [Bolna enterprise](/enterprise/plan).
# Deleting a Sub-account
Source: https://www.bolna.ai/docs/api-reference/sub-accounts/delete
DELETE /sub-accounts/{sub_account_id}
Use Bolna APIs to delete a sub-account and their related data, ensuring proper cleanup of agents, batches, executions, and configurations.
This deletes **ALL** the data for that sub-account's batches, executions and agents.
# List all Sub-Accounts API
Source: https://www.bolna.ai/docs/api-reference/sub-accounts/get_all
GET /sub-accounts/all
Retrieve all sub-accounts linked to your main account enabling centralized visibility and management.
This is an `enterprise` feature.
You can read more about our enterprise offering here [Bolna enterprise](/enterprise/plan).
# Sub accounts APIs overview
Source: https://www.bolna.ai/docs/api-reference/sub-accounts/overview
Manage multiple customers or business units with Bolna Sub-Accounts API. Create, list, and track usage with clear data separation and control.
This is an `enterprise` feature.
You can read more about our enterprise offering here [Bolna enterprise](/enterprise/plan).
## Endpoints
```
POST /sub-accounts/create
GET /sub-accounts/all
GET /sub-accounts/:sub_account_id/usage
```
# Patch Update a Sub-account
Source: https://www.bolna.ai/docs/api-reference/sub-accounts/patch_update
PATCH /sub-accounts/{sub_account_id}
Use this Bolna API endpoint to partially modify and update sub-account properties, including its name, concurrency limits, and call capacity settings.
Currently, only the following agent attributes can be updated for the `PATCH` update.
* `allow_concurrent_calls`
* `name`
# Track Sub-Account Usage API
Source: https://www.bolna.ai/docs/api-reference/sub-accounts/usage
GET /sub-accounts/{sub_account_id}/usage
Track usage for a specific sub-account giving you fine-grained insights into usage, consumption and billing.
This is an `enterprise` feature.
You can read more about our enterprise offering here [Bolna enterprise](/enterprise/plan).
# Add a New Custom LLM Model
Source: https://www.bolna.ai/docs/api-reference/user/add_model
POST /user/model/custom
Learn how to integrate your custom Large Language Model (LLM) with Bolna Voice AI agents using Bolna APIs.
This request specifies how to add your own Custom LLM Models and use it with Bolna Voice AI agents. Please read about it more from [using-custom-llm](/customizations/using-custom-llm)
# User information
Source: https://www.bolna.ai/docs/api-reference/user/info
GET /user/me
Get details like name, email, current wallet balance, concurrency limits using this API
# User APIs Overview
Source: https://www.bolna.ai/docs/api-reference/user/overview
Explore APIs related to user and account information for Bolna Voice AI agents, including endpoints for adding custom LLM models.
## Endpoints
```
GET /user/me
POST /user/model/custom
```
# List All Voices API
Source: https://www.bolna.ai/docs/api-reference/voice/get_all
GET /me/voices
Retrieve a list of all available voices for your account, including details like provider, language, and accent.
# Voice APIs Overview
Source: https://www.bolna.ai/docs/api-reference/voice/overview
APIs for accessing voices and generating test transcripts which can be utilized for Bolna Voice AI agents.
## Endpoints
```
GET /me/voices
```
# Auto-Retry for Failed Calls
Source: https://www.bolna.ai/docs/auto-retry
Automatically retry calls that fail due to no-answer, busy signals, or errors to improve contact rates.
## What is auto-retry?
Auto-retry automatically reschedules calls that fail to connect. When a call ends with statuses like no-answer or busy, Bolna can automatically retry the call after a configurable delay.
## How to enable auto-retry
Add the `retry_config` object when making a call via the [Make Call API](/api-reference/calls/make) or [Create Batch API](/api-reference/batches/create).
```bash Single Call theme={"system"}
curl -X POST 'https://api.bolna.ai/call' \
-H 'Authorization: Bearer ' \
-H 'Content-Type: application/json' \
-d '{
"agent_id": "your-agent-id",
"recipient_phone_number": "+1234567890",
"retry_config": {
"enabled": true,
"max_retries": 3,
"retry_on_statuses": ["no-answer", "busy", "failed"],
"retry_intervals_minutes": [30, 60, 120]
}
}'
```
```bash Batch Call theme={"system"}
curl -X POST 'https://api.bolna.ai/batches' \
-H 'Authorization: Bearer ' \
-F 'agent_id=your-agent-id' \
-F 'file=@contacts.csv' \
-F 'retry_config={"enabled":true,"max_retries":2,"retry_intervals_minutes":[15,30]}'
```
## Configuration options
| Parameter | Type | Default | Description |
| ------------------------- | ------- | --------------------------------- | --------------------------- |
| `enabled` | boolean | `false` | Enable auto-retry |
| `max_retries` | integer | `3` | Max retry attempts (1-3) |
| `retry_on_statuses` | array | `["no-answer", "busy", "failed"]` | Statuses that trigger retry |
| `retry_on_voicemail` | boolean | `false` | Retry if voicemail detected |
| `retry_intervals_minutes` | array | `[30, 60, 120]` | Delay before each retry |
### Supported retry statuses
* `no-answer` - Call rang but wasn't answered
* `busy` - Line was busy
* `failed` - Call failed to connect
* `error` - Technical error occurred
## Monitoring retries via webhook
When auto-retry is configured, your webhook receives retry information:
```json theme={"system"}
{
"id": "execution-id",
"status": "scheduled",
"retry_count": 1,
"retry_config": {
"enabled": true,
"max_retries": 3
},
"retry_history": [
{
"attempt": 1,
"status": "no-answer",
"at": "2026-01-26T10:00:00Z"
}
],
"scheduled_at": "2026-01-26T10:30:00Z"
}
```
## Best practices
* Start with conservative intervals (30+ minutes) to avoid annoying contacts
* Use `retry_on_voicemail: false` (default) to avoid repeated voicemail deposits
* Monitor `retry_count` in webhooks to track retry effectiveness
* Set `max_retries` based on campaign urgency (1-2 for time-sensitive, 3 for lead outreach)
## Related features
* [Batch Calling](/batch-calling) - Run campaigns with thousands of contacts
* [Webhooks](/polling-call-status-webhooks) - Get real-time call status updates
* [Call Details](/call-details) - View execution history and outcomes
# Automate and schedule calls using Batches
Source: https://www.bolna.ai/docs/batch-calling
Learn how to schedule and manage batch calls using Bolna's Voice AI agents. Upload CSV files, set call parameters, and monitor execution for efficient outreach.
## What is batch calling in Bolna?
Batch calling allows you to automate outbound calls to hundreds or thousands of contacts by uploading a CSV file with phone numbers and custom data. This feature is perfect for lead qualification, customer outreach, appointment reminders, and other high-volume calling campaigns.
## How should I structure my batch CSV file?
1. All phone numbers should include the country prefix in [E.164](https://en.wikipedia.org/wiki/E.164) format
2. All phone numbers should have `contact_number` as the header
3. All other variables can be included in the CSV file in separate coloumns
###
```csv example_batch_file.csv theme={"system"}
contact_number,first_name,last_name
+11231237890,Bruce,Wayne
+91012345678,Bruce,Lee
+00021000000,Satoshi,Nakamoto
+44999999007,James,Bond
```
## How to export a CSV file from Excel or Google Sheets?
In Excel, when you type a `+` at the beginning of a cell, Excel interprets it as a formula.
To ensure the plus sign `+` is retained when entering phone numbers with country codes,
**please add an apostrophe (`'`) before the plus sign.**
[Download an example CSV file](https://bolna-public.s3.amazonaws.com/Bolna+batch+calling+example+csv.csv)
***
## How to use Batch APIs step by step?
### i. Create a batch for agent
Once the CSV file is ready, upload it using the [Create Batch API](/api-reference/batches/create)
```bash request theme={"system"}
curl --location 'https://api.bolna.ai/batches' \
--header 'Authorization: Bearer ' \
--form 'agent_id="aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"' \
--form 'file=@"/my-first-batch.csv"'
```
```bash response theme={"system"}
{
"batch_id": "abcdefghijklmnopqrstuvwxyz012345",
"state": "created"
}
```
### ii. Scheduling the batch
After receiving your `batch_id`, you can schedule a batch using [Schedule Batch API](/api-reference/batches/schedule)
The scheduled date and time should be in **ISO 8601** format with time zone.
```bash request theme={"system"}
curl --location 'https://api.bolna.ai/batches/abcdefghijklmnopqrstuvwxyz012345/schedule' \
--header 'Authorization: Bearer ' \
--form 'scheduled_at="2024-03-20T04:05:00+00:00"'
```
```bash response theme={"system"}
{
"message": "success",
"state": "scheduled at 2024-03-20T04:10:00+00:00"
}
```
### iii. Retrieving batch status
Check the status of the batch using [Get Batch API](/api-reference/batches/get_batch)
```bash request theme={"system"}
curl --location 'https://api.bolna.ai/batches/abcdefghijklmnopqrstuvwxyz012345' \
--header 'Authorization: Bearer '
```
```bash response theme={"system"}
{
"batch_id": "abcdefghijklmnopqrstuvwxyz012345",
"humanized_created_at": "19 minutes ago",
"created_at": "2024-03-13T14:12:50.596315",
"updated_at": "2024-03-13T14:19:13.115411",
"status": "scheduled",
"scheduled_at": "2024-03-20T04:10:00+05:30"
}
```
### iv. Retrieving all batch executions
Once the batch has run, you can check all executions by the agent using [List Batch Executions API](/api-reference/batches/executions)
```bash request theme={"system"}
curl --location 'https://api.bolna.ai/batches/abcdefghijklmnopqrstuvwxyz012345/executions' \
--header 'Authorization: Bearer '
```
```bash response theme={"system"}
[
{
"id": 7432382142914,
"conversation_time": 123,
"total_cost": 123,
"transcript": "",
"createdAt": "2024-01-23T01:14:37Z",
"updatedAt": "2024-01-29T18:31:22Z",
"usage_breakdown": {
"synthesizerCharacters": 123,
"synthesizerModel": "polly",
"transcriberDuration": 123,
"transcriberModel": "deepgram",
"llmTokens": 123,
"llmModel": {
"gpt-3.5-turbo-16k": {
"output": 28,
"input": 1826
},
"gpt-3.5-standard-8k": {
"output": 20,
"input": 1234
}
}
}
},
{...},
{...},
{...},
{...}
]
```
## Complete example: Building a batch calling application
```python batch_script.py theme={"system"}
import asyncio
import os
from dotenv import load_dotenv
import aiohttp
# Load environment variables from .env file
load_dotenv()
# Load from .env
host = "https://api.bolna.ai"
api_key = os.getenv("api_key", None)
agent_id = 'ee153a6c-19f8-3a61-989a-9146a31c7834' #agent_id in which we want to create the batch
file_path = '/path/of/csv/file'
schedule_time = '2024-06-01T04:10:00+05:30'
async def schedule_batch(api_key, batch_id, scheduled_at):
print("now scheduling batch for batch id : {}".format(batch_id))
url = f"{host}/batches/{batch_id}/schedule"
headers = {'Authorization': f'Bearer {api_key}'}
data = {
'scheduled_at': scheduled_at
}
try:
async with aiohttp.ClientSession() as session:
async with session.post(url, headers=headers, data=data) as response:
response_data = await response.json()
if response.status == 200:
return response_data
else:
raise Exception(f"Error scheduling batch: {response_data}")
except aiohttp.ClientError as e:
print(f"HTTP Client Error: {str(e)}")
except Exception as e:
print(f"Unexpected error: {str(e)}")
async def get_batch_status(api_key, batch_id):
print("now getting batch status for batch id : {}".format(batch_id))
url = f"{host}/batches/{batch_id}"
headers = {'Authorization': f'Bearer {api_key}'}
try:
async with aiohttp.ClientSession() as session:
async with session.get(url, headers=headers) as response:
response_data = await response.json()
if response.status == 200:
return response_data
else:
raise Exception(f"Error getting batch status: {response_data}")
except aiohttp.ClientError as e:
print(f"HTTP Client Error: {str(e)}")
except Exception as e:
print(f"Unexpected error: {str(e)}")
async def get_batch_executions(api_key, batch_id):
print("now getting batch executions for batch id : {}".format(batch_id))
url = f"{host}/batches/{batch_id}/executions"
headers = {'Authorization': f'Bearer {api_key}'}
try:
async with aiohttp.ClientSession() as session:
async with session.get(url, headers=headers) as response:
response_data = await response.json()
if response.status == 200:
return response_data
else:
raise Exception(f"Error getting batch executions: {response_data}")
except aiohttp.ClientError as e:
print(f"HTTP Client Error: {str(e)}")
except Exception as e:
print(f"Unexpected error: {str(e)}")
async def create_batch():
url = f"{host}/batches"
headers = {'Authorization': f'Bearer {api_key}'}
with open(file_path, 'rb') as f:
form_data = aiohttp.FormData()
form_data.add_field('agent_id', agent_id)
form_data.add_field('file', f, filename=os.path.basename(file_path))
async with aiohttp.ClientSession() as session:
async with session.post(url, headers=headers, data=form_data) as response:
response_data = await response.json()
if response_data.get('state') == 'created':
batch_id = response_data.get('batch_id')
res = await schedule_batch(api_key, batch_id, scheduled_at=schedule_time)
if res.get('state') == 'scheduled':
check = True
while check:
# Checking the current status every 1 minute
await asyncio.sleep(60)
res = await get_batch_status(api_key, batch_id)
if res.get('status') == 'completed':
check = False
break
if not check:
res = await get_batch_executions(api_key, batch_id)
print(res)
return res
if __name__ == "__main__":
asyncio.run(create_batch())
```
## Next steps
Ready to implement batch calling? Start by [creating your first batch](/api-reference/batches/create) via the API or explore related features:
* Learn about [outbound calling concurrency](/outbound-calling-concurrency) limits
* Set up [dedicated phone numbers](/buying-phone-numbers) for your campaigns
* Configure [context variables](/using-context) to personalize each call
* Monitor [call details](/call-details) and execution results
For high-volume needs, consider the [Enterprise Plan](/enterprise/plan) with elevated concurrency limits and priority processing.
# Acquire Dedicated Phone Numbers through Bolna
Source: https://www.bolna.ai/docs/buying-phone-numbers
Purchase and manage phone numbers directly from Bolna's dashboard. Follow step-by-step instructions to secure numbers for your Voice AI agents.
Buy and view your Phone numbers on [https://platform.bolna.ai/phone-numbers](https://platform.bolna.ai/phone-numbers).
## Detailed steps to purchase phone numbers
All phone numbers are purchased for a monthly recurring cost and the amounts are deducted from the Bolna wallet balance. View [call pricing](/pricing/call-pricing) for more details on costs.
## What can I do with my purchased phone numbers?
Once you've purchased phone numbers, you can:
* [Make outbound calls](/making-outgoing-calls) from your dedicated numbers
* [Receive inbound calls](/receiving-incoming-calls) to your Voice AI agents
* [Configure telephony providers](/supported-telephony-providers) like Twilio or Plivo
* [Run batch calling campaigns](/batch-calling) at scale
# Extract Structured Data from Conversations in Bolna Voice AI
Source: https://www.bolna.ai/docs/call-details
Access detailed insights into call logs and data with Bolna Voice AI. Learn how to analyze and utilize call details for better decision-making.
## What is data extraction in Bolna?
Data extraction allows you to automatically capture specific information from voice conversations in a structured JSON format. This is essential for CRM integration, lead qualification, appointment booking, and post-call analysis.
## How to extract call details in structured JSON format?
By defining any relevant information you wish to extract from the conversation, you can use `Extraction prompt`.
Post every call, you'll get this data in the [Execution](/api-reference/executions/get_execution) payload in `extracted_data` key.
### Example
```text extraction prompt theme={"system"}
user_name : Yield the name of the user.
payment_mode : If user is paying by cash, yield cash. If they are paying by card yield card. Else yield NA
payment_date: yield payment date by the user in YYYY-MM-DD format
```
```json response theme={"system"}
...
...
"extracted_data": {
"user_name": "Bruce",
"payment_mode": "paypal,
"payment_date": "2024-12-30"
},
...
...
```
## What can I extract from calls?
You can extract any information discussed during the conversation:
* **Customer information**: Names, email addresses, phone numbers
* **Appointment details**: Dates, times, preferences
* **Lead qualification data**: Budget, timeline, decision-maker status
* **Payment information**: Payment method, amount, date
* **Product preferences**: Sizes, colors, quantities
* **Feedback and sentiment**: Satisfaction scores, complaints, compliments
## Next steps
Ready to implement data extraction? Configure extraction prompts in your agent or explore related features:
* Use [context variables](/using-context) to pre-fill known information
* Access extraction data via the [Executions API](/api-reference/executions/get_execution)
* Integrate with [custom functions](/tool-calling/custom-function-calls) for real-time actions
* Set up [batch calling](/batch-calling) with personalized context per call
For advanced use cases, combine extraction with [multi-agent workflows](/multi-agent-prompt) for complex conversations.
# Agent Conversations, Metrics & Logs
Source: https://www.bolna.ai/docs/call-history
Access all Voice AI agent conversations, recordings, transcripts, and execution data. Monitor performance metrics, debug with trace logs, and export call data for analysis.
## What is Call History?
Call History (Agent Conversations) displays all historical conversations with your agents. View performance metrics, listen to recordings, read transcripts, and access raw execution data for debugging and analysis.
***
## How to Access Call History
Click **Call History** in the left navigation menu.
Click **See all call logs** in the actions panel.
***
## Performance Metrics
The top section displays **real-time metrics** for your selected agent and date range. Use these to monitor campaign performance at a glance.
| Metric | Description |
| -------------------- | ---------------------------------------------- |
| **Total Executions** | Total number of call attempts |
| **Total Cost** | Total campaign spend |
| **Total Duration** | Total call time in seconds |
| **Status Breakdown** | Count of Error, Completed, and No-Answer calls |
| **Avg Cost** | Average cost per call |
| **Avg Duration** | Average call length |
***
## Filtering Calls
| Filter | Description |
| -------------- | ----------------------------------------- |
| **Agent** | Select a specific agent to view its calls |
| **Batch** | Filter by batch campaign |
| **Date Range** | Choose a date range for the calls |
| **Group By** | Group calls by different criteria |
| **Call Type** | Filter by inbound or outbound calls |
| **Status** | Filter by Completed, Error, or No-Answer |
| **Provider** | Filter by telephony provider |
Use the **search by execution ID** box to quickly find a specific call.
***
## Call Table
Each call is displayed with the following information:
| Column | Description |
| --------------------- | --------------------------------------------------- |
| **Execution ID** | Unique identifier for the call |
| **User Number** | Phone number of the caller/recipient |
| **Conversation Type** | Type of call (plivo outbound, twilio inbound, etc.) |
| **Duration (s)** | Call duration in seconds |
| **Hangup By** | Who ended the call (Callee, Carrier, Plivo, etc.) |
| **Batch** | Batch campaign if applicable |
| **Timestamp** | When the call occurred |
| **Cost** | Cost of the call |
| **Status** | Call status (Completed, No-answer, Error) |
***
## Call Details
Click **Recordings, transcripts, etc** to view the full conversation data.
| Section | Description |
| -------------- | ----------------------------------------------------- |
| **Recording** | Audio waveform with play, copy, and download options |
| **Transcript** | Full conversation showing Assistant and User messages |
Use the copy button to quickly copy the recording URL or transcript text.
Click the **Trace Data** icon to view detailed execution logs for debugging.
| Column | Description |
| ------------- | ---------------------------------------------------------- |
| **Timestamp** | Exact time of each log entry |
| **Log Data** | The actual request or response content |
| **Direction** | Whether it's a request or response |
| **Component** | Which component handled it (synthesizer, transcriber, llm) |
| **Provider** | Provider used (elevenlabs, deepgram, azure, etc.) |
**Trace data is essential for debugging!** Use it to identify latency issues, transcription errors, or unexpected LLM responses.
Click **Download logs** to export all trace data for detailed analysis.
Click the **Raw Data** icon to view the complete JSON execution data.
The raw data format matches the [Get Execution API](/api-reference/executions/get_execution) response, making it easy to integrate with your systems programmatically.
***
## Quick Actions
| Action | Description |
| --------------------- | --------------------------------- |
| **Refresh** | Reload the call list |
| **Stop Queued Calls** | Cancel pending calls in the queue |
| **Download Records** | Export call data as CSV |
Export call data as CSV for analysis in spreadsheet tools or to share with your team.
***
## Next Steps
Configure webhooks and post-call tasks
Access call data programmatically
Configure your agent settings
Set up automated calling campaigns
# Understanding Latency Metrics in Voice AI Executions
Source: https://www.bolna.ai/docs/call-latencies
Comprehensive guide to analyzing latency in Bolna Voice AI. Explore performance insights across transcription, LLM processing, and speech synthesis.
## Introduction
Bolna provides detailed latency metrics for every Voice AI execution, allowing you to monitor and optimize the performance of your conversational AI agents. These metrics help you understand where time is being spent in the conversation pipeline and identify potential bottlenecks that may affect user experience.
The latency data is included in the execution payload when you fetch execution details via the [Get Execution API](/api-reference/executions/get_execution). This data provides granular timing information across all major components of the voice AI pipeline.
## Latency Data Structure
The `latency_data` object in the execution payload contains timing information organized by component. Here's the complete structure:
### Top-Level Metrics
```json theme={"system"}
{
"latency_data": {
"stream_id": 129.56982,
"time_to_first_audio": 130.84888,
"region": "in",
"transcriber": {
"time_to_connect": 226,
"turns": [...]
},
"llm": {
"time_to_connect": null,
"turns": [...]
},
"synthesizer": {
"time_to_connect": 271,
"turns": [...]
}
}
}
```
| Field | Type | Description |
| --------------------- | ------ | -------------------------------------------------------------------------------------------------------- |
| `stream_id` | float | Time in milliseconds to establish the audio stream connection |
| `time_to_first_audio` | float | Total time in milliseconds from call start until the first audio is played to the user |
| `region` | string | Geographic region code where the execution occurred (e.g., `in` for India, `us` for United States) |
## Transcriber Metrics
The transcriber component converts spoken audio into text. This section tracks how quickly speech is being transcribed.
```json theme={"system"}
{
"transcriber": {
"time_to_connect": 226,
"turns": [
{
"turn": 1,
"turn_latency": [
{
"sequence_id": 1,
"audio_to_text_latency": 20.12128,
"text": "hello who is there"
},
{
"sequence_id": 2,
"audio_to_text_latency": 19.96126,
"text": "hello who is this"
}
]
}
]
}
}
```
### Field Definition
| Field | Type | Description |
| ------------------------------- | --------------- | ------------------------------------------------------------------------ |
| `time_to_connect` | `integer` | Time (ms) to establish connection with the transcriber provider. |
| `turns` | `array