# Bolna

Create conversational voice agents using Bolna AI to enhance interactions, streamline operations and automate support.

- **Category:** ai agents
- **Auth:** API_KEY
- **Composio Managed App Available?** N/A
- **Tools:** 35
- **Triggers:** 0
- **Slug:** `BOLNA`
- **Version:** 20260312_00

## Tools

### Add Provider to Bolna

**Slug:** `BOLNA_ADD_PROVIDER`

Tool to add a new telephony or voice service provider to your Bolna account. Use when you need to configure API keys for providers like Twilio, Deepgram, or ElevenLabs before creating agents.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | string | No | User ID to associate the provider with. Optional. |
| `provider_name` | string | Yes | Name of the telephony or voice service provider to add (e.g., 'twilio', 'deepgram', 'elevenlabs') |
| `is_api_request` | boolean | No | Flag indicating if this is an API request. Defaults to false. |
| `provider_value` | string | Yes | API key or authentication value for the provider |
| `sub_account_id` | string | No | Sub-account ID to associate the provider with. Optional. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Copy Bolna Agent

**Slug:** `BOLNA_COPY_AGENT`

Tool to create a duplicate copy of an existing Bolna voice AI agent. Use when you need to replicate an agent's complete configuration (tasks, prompts, LLM settings, etc.) with a new name.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | string | No | Optional user identifier to associate the copied agent with a specific user |
| `agent_id` | string | Yes | The unique identifier (UUID) of the existing Bolna agent to copy |
| `agent_name` | string | Yes | The name for the new copied agent. This will be the display name of the duplicated agent. |
| `is_api_request` | boolean | No | Flag to indicate if this is an API request. Defaults to false if not provided. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Bolna Voice AI Agent (v2)

**Slug:** `BOLNA_CREATE_AGENT`

Tool to create a new Bolna Voice AI agent using the v2 API. Use when you need to set up a new conversational agent from scratch with custom LLM, synthesizer, transcriber, and task configurations. This fills the gap for end-to-end agent setup in workflows starting from an empty account state.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_config` | object | Yes | Complete agent configuration object. Required fields: agent_name (string), agent_type (string: 'other', 'sales', 'support', etc.), agent_welcome_message (string), webhook_url (string URL for callbacks), and tasks (array). Each task must include task_type ('conversation', 'extraction', or 'summarization'), toolchain (with execution mode and pipelines), tools_config (defining input/output providers, transcriber, llm_agent, and synthesizer), and task_config (with settings like hangup_after_silence). |
| `agent_prompts` | object | Yes | Object containing prompt configurations for each task. Each task key (e.g., 'task_1', 'task_2') maps to an object with a 'system_prompt' string that defines behavioral instructions for that task. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Bolna Batch

**Slug:** `BOLNA_CREATE_BATCH`

Tool to create a new outbound calling batch by uploading a CSV of contacts to obtain a batch_id. Use when initiating a batch campaign; follow by calling BOLNA_SCHEDULE_BATCH_BY_ID to schedule execution.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file` | object | Yes | CSV file containing contact numbers and prompt variable details for batch execution. |
| `agent_id` | string | Yes | The ID of the agent (UUID format) to use for the batch calling campaign |
| `from_phone_number` | string | No | Phone number in E.164 format (e.g., '+19876543007') to use as the caller ID when initiating batch calls. If not provided, system defaults will be used. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Bolna Knowledgebase

**Slug:** `BOLNA_CREATE_KNOWLEDGEBASE`

Tool to create a new knowledgebase for Voice AI agents to reference during conversations. Use when you need to provide agents with domain-specific knowledge from PDFs or web URLs. Note: Initially returns status 'processing'; poll or wait for status to become 'processed' before use.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | No | URL to ingest as the knowledgebase source (e.g., 'https://example.com/documentation'). Either 'url' or 'file' must be provided, but not both. Use this for web-based content. |
| `file` | object | No | PDF file to upload as the knowledgebase source. Either 'file' or 'url' must be provided, but not both. |
| `user_id` | string | No | Optional user identifier to associate with this knowledgebase |
| `chunk_size` | integer | No | Size of text chunks to split the content into for vector embeddings. Larger chunks preserve more context but may reduce retrieval precision. Typical values: 200-1000. |
| `overlapping` | integer | No | Number of characters to overlap between consecutive chunks. Overlapping helps preserve context across chunk boundaries. Typical values: 50-200. |
| `is_api_request` | boolean | No | Internal flag to indicate if this is an API request. Typically not needed by end users. |
| `sub_account_id` | string | No | Optional sub-account identifier for multi-tenant environments |
| `similarity_top_k` | integer | No | Number of most similar chunks to retrieve during agent queries. Higher values provide more context but may include less relevant information. Typical values: 1-10. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Template Agent

**Slug:** `BOLNA_CREATE_TEMPLATE_AGENT`

Tool to create a new Bolna Voice AI agent from a template. Use when you want to quickly set up an agent using predefined templates instead of building from scratch.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | No | System prompt or instructions that define the agent's behavior and responses. This guides how the agent interacts with users. |
| `user_id` | string | No | Optional user ID to associate with the template agent |
| `agent_name` | string | No | Name for the template agent being created. This will identify the agent in the system. |
| `agent_type` | string | No | Type or category of the agent template. Specifies the functional role of the agent (e.g., 'support', 'sales', 'other'). |
| `transcript` | boolean | No | Flag indicating whether to enable transcript recording for this agent. Set to true to capture conversation transcripts. |
| `business_name` | string | No | Name of the business for which the template agent is being created |
| `return_prompt` | boolean | No | Flag indicating whether to return the generated prompt in the response. Set to true to receive the prompt back after agent creation. |
| `variable_dict` | object | No | Dictionary of custom variables that can be used in the agent template. Allows dynamic substitution of values in prompts and configurations. Keys and values should be strings. |
| `about_business` | string | No | Description of the business for which the agent template is being created. Provides context about the business domain and purpose. |
| `is_api_request` | string | No | Optional flag indicating if this is an API request. Accepts string representation of boolean (e.g., 'true', 'false'). Default is 'false' if not provided. |
| `template_agent` | string | No | Identifier or name of the base template to use for agent creation. References a predefined agent template. |
| `service_details` | string | No | Details about the services offered by the business. Helps the agent understand what services it can discuss with customers. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete agent by id

**Slug:** `BOLNA_DELETE_AGENT_BY_ID`

Permanently delete a Voice AI agent and all associated data including batches, executions, and configurations

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | Unique identifier (UUID) of the agent to delete. WARNING: This will permanently delete ALL agent data including all batches, executions, and configurations. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete batch by id

**Slug:** `BOLNA_DELETE_BATCH_BY_ID`

Permanently delete a batch campaign by its ID, removing it from the system. This operation cannot be undone.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `batch_id` | string | Yes | Unique identifier (UUID format) of the batch to delete. This will permanently remove the batch and cannot be undone. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Knowledgebase

**Slug:** `BOLNA_DELETE_KNOWLEDGEBASE`

Tool to permanently delete a knowledgebase from your Bolna account. Use when you need to remove an existing RAG knowledgebase that is no longer needed. This operation cannot be undone.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `rag_id` | string | Yes | Unique identifier (UUID format) of the knowledgebase to delete. This will permanently remove the knowledgebase and cannot be undone. |
| `user_id` | string | No | Optional user identifier to scope the deletion operation to a specific user account |
| `is_api_request` | string | No | Flag indicating whether this is an API request. Typically omitted or set to false for standard operations |
| `sub_account_id` | string | No | Optional sub-account identifier for multi-tenant or organization scenarios |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Fetch all batches by agent id

**Slug:** `BOLNA_FETCH_ALL_BATCHES_BY_AGENT_ID`

Retrieve all batches associated with a specific Bolna Voice AI agent. Returns a comprehensive list of batches with details including batch status (scheduled, created, queued, executed), creation and scheduled times, contact counts, file names, and execution status breakdown. Use this to monitor batch campaigns, track their progress, and manage outbound calling operations for the agent.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | The unique identifier (UUID) of the Bolna Voice AI agent whose batches you want to retrieve |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Agent (v1 - Deprecated)

**Slug:** `BOLNA_GET_AGENT_V1`

[DEPRECATED] Retrieve Voice AI agent details using the v1 API endpoint. Use GET /v2/agent/{agent_id} (retrieve_agent_by_id) instead for current implementations. This action returns agent configuration including name, type, status, tasks, and prompts.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | string | No | Optional user identifier to filter agents by user ownership. |
| `agent_uuid` | string | Yes | The unique identifier (UUID) of the Bolna voice agent to retrieve. You can get valid agent IDs from the get_all_agents action. |
| `is_api_request` | string | No | Flag indicating if this is an API request. Defaults to false if not provided. |
| `sub_account_id` | string | No | Optional sub-account identifier for multi-tenant scenarios. |
| `agent_version_id` | string | No | Optional version identifier to retrieve a specific version of the agent. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get all agents

**Slug:** `BOLNA_GET_ALL_AGENTS`

Retrieve all agents configured in your Bolna account Returns a comprehensive list of all voice agents with their configurations including: - Agent metadata (ID, name, type, status) - Task configurations (conversation settings, toolchains) - AI model settings (LLM, transcriber, synthesizer) - Webhook and phone number assignments - System prompts and guardrails This is useful for listing available agents, checking agent configurations, or finding specific agents by their properties.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get execution by id

**Slug:** `BOLNA_GET_EXECUTION_BY_ID`

Retrieve detailed information about a specific phone call execution by its ID. Returns comprehensive execution data including conversation transcript, duration, costs (LLM, TTS, STT, network, platform), telephony details (phone numbers, recording URL, provider info), usage metrics (tokens, characters, duration), and extracted structured data. Use this to: - Analyze individual call performance and outcomes - Access conversation transcripts and recordings - Review cost breakdowns and resource usage - Monitor call status and error messages - Retrieve extracted structured data from conversations

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `execution_id` | string | Yes | The unique execution identifier (UUID format, e.g., '4c06b4d1-4096-4561-919a-4f94539c8d4a') |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get knowledgebase by ID

**Slug:** `BOLNA_GET_KNOWLEDGEBASE`

Tool to retrieve details of a specific knowledgebase by its ID. Returns complete configuration including processing status, file information, vector ID, and embedding parameters (chunk size, similarity top k, overlapping). Use when you need to check if a knowledgebase has finished processing or to inspect its configuration before using it with an agent.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `rag_id` | string | Yes | The unique identifier (UUID) of the knowledgebase to retrieve |
| `user_id` | string | No | Optional user ID for filtering knowledgebase access |
| `is_api_request` | boolean | No | Flag indicating if this is an API request |
| `sub_account_id` | string | No | Optional sub-account ID for multi-tenant scenarios |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get User Information

**Slug:** `BOLNA_GET_USER_INFO`

Tool to retrieve information about the authenticated user. Use when you need details like name, email, wallet balance, or concurrency limits for the current user.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | string | No | Optional user ID to fetch information for a specific user |
| `is_api_request` | boolean | No | Flag to indicate if this is an API request |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Import Bolna Agent

**Slug:** `BOLNA_IMPORT_AGENT`

Tool to import an existing Bolna voice AI agent by its ID. Use when you need to copy or duplicate an agent configuration, create a new agent from a template, or migrate an agent from another environment.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | string | No | Optional user identifier to associate with the imported agent |
| `agent_id` | string | Yes | The unique identifier (UUID format) of the agent to import |
| `agent_name` | string | No | Optional name to assign to the imported agent. If not provided, the original agent name will be used. |
| `is_api_request` | boolean | No | Flag indicating whether this is an API request. Defaults to false if not provided. |
| `sub_account_id` | string | No | Optional sub-account identifier for multi-tenant environments |
| `agent_version_id` | string | No | Optional version identifier (UUID format) of the specific agent version to import. If not provided, the latest version will be imported. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List agents (paginated)

**Slug:** `BOLNA_LIST_AGENTS_PAGINATED`

Tool to retrieve a paginated list of all agents in your Bolna account. Use when you need to fetch agents with optional filtering by user_id or sub_account_id.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | string | No | Filter agents by specific user ID |
| `is_api_request` | string | No | Flag to indicate if this is an API request. Accepts string representation of boolean. |
| `sub_account_id` | string | No | Filter agents by sub-account ID for multi-tenant scenarios |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Knowledgebases

**Slug:** `BOLNA_LIST_KNOWLEDGEBASES`

Tool to retrieve all knowledgebases from your Bolna account. Use when you need to view available RAG knowledgebases, check their processing status, or find specific knowledgebases by status.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string ("processing" | "processed") | No | Status of a knowledgebase |
| `user_id` | string | No | Optional user identifier to filter knowledgebases by a specific user account |
| `is_api_request` | string | No | Flag indicating whether this is an API request. Typically omitted or set to false for standard operations |
| `sub_account_id` | string | No | Optional sub-account identifier for multi-tenant or organization scenarios |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List all phone numbers

**Slug:** `BOLNA_LIST_PHONE_NUMBERS`

Tool to list all phone numbers associated with your Bolna account. Use when you need to retrieve details of all phone numbers including provider, associated agent, pricing, and rental status.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List all providers

**Slug:** `BOLNA_LIST_PROVIDERS`

Retrieve all providers associated with your Bolna account Returns a list of all configured providers including: - Provider IDs (unique identifiers) - Provider names (e.g., API key types) - Masked provider values (secrets) - Creation timestamps (both absolute and human-readable) Use this when you need to view all configured API providers, check provider details, or verify provider setup in your Bolna account.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List available voices

**Slug:** `BOLNA_LIST_VOICES`

Tool to list all available voices that can be utilized for Voice AI agents. Use when you need to see which voices are available across different providers.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | string | No | Optional user ID to filter voices for a specific user |
| `is_api_request` | string | No | Optional flag to indicate if this is an API request |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Make an outbound phone call from agent

**Slug:** `BOLNA_MAKE_A_PHONE_CALL_FROM_AGENT`

Initiate an outbound phone call using a configured Bolna Voice AI agent. The agent will call the specified recipient and engage in a conversation based on its configured prompt and capabilities.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | The UUID of the Bolna agent that will initiate and handle the outbound call. Use get_all_agents to retrieve available agent IDs. |
| `user_data` | object | No | Optional dictionary of custom variables that can be referenced in the agent's prompt template. Keys should match variable names in your agent configuration. Example: {'customer_name': 'John', 'order_id': '12345'} |
| `from_phone_number` | string | No | Optional caller ID phone number in E.164 format (e.g., +14155559999). If not provided, Bolna will use a default shared number. Required only when using dedicated or connected phone numbers. |
| `recipient_phone_number` | string | Yes | The recipient's phone number in E.164 international format (e.g., +14155552671 for US, +919876543210 for India). Must include the + prefix and country code. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Partially Update Bolna Voice AI Agent (v1)

**Slug:** `BOLNA_PATCH_AGENT_V1`

Tool to partially update a Voice AI agent using the v1 API endpoint. Use when you need to modify specific agent properties like name, welcome message, webhook URL, synthesizer settings, or system prompts without providing the full configuration. Note: This is a deprecated v1 endpoint; prefer using PATCH /v2/agent/{agent_id} for new implementations.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | string | No | User identifier for multi-tenant scenarios |
| `agent_uuid` | string | Yes | Unique identifier (UUID) of the agent to update. Also known as agent_id. |
| `agent_config` | object | No | Schema for agent configuration |
| `agent_prompts` | object | No | Schema for agent prompts configuration |
| `is_api_request` | boolean | No | Flag indicating if this is an API request |
| `sub_account_id` | string | No | Sub-account identifier for organizational hierarchy |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Remove Provider from Bolna Account

**Slug:** `BOLNA_REMOVE_PROVIDER`

Tool to remove a provider from your Bolna account by its key name. Use when you need to delete a provider configuration that is no longer needed or needs to be replaced.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | string | No | Optional user ID to scope the provider removal to a specific user |
| `is_api_request` | boolean | No | Flag to indicate if this is an API request. Defaults to false if not specified |
| `sub_account_id` | string | No | Optional sub-account ID to scope the provider removal to a specific sub-account |
| `provider_key_name` | string | Yes | The unique key name of the provider to remove from your account (e.g., 'TEST_PROVIDER') |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Retrieve agent by id

**Slug:** `BOLNA_RETRIEVE_AGENT_BY_ID`

Retrieve complete configuration and details for a specific Bolna voice AI agent by its ID. Returns comprehensive agent information including name, type, status, conversation tasks, LLM/synthesizer/transcriber settings, system prompts, webhook configuration, and timestamps. Use this to inspect agent setup before making calls or to verify agent configuration.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | The unique identifier (UUID) of the Bolna voice agent to retrieve. You can get valid agent IDs from the get_all_agents action. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Retrieve agent execution details

**Slug:** `BOLNA_RETRIEVE_AGENT_EXECUTION_DETAILS`

Retrieve detailed information about a specific execution (call/conversation) by an agent, including transcript, costs, duration, status, and telephony data

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | The unique agent ID (UUID format) |
| `execution_id` | string | Yes | The unique execution ID for the call/conversation (UUID format) |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Retrieve agent execution status

**Slug:** `BOLNA_RETRIEVE_AGENT_EXECUTION_STATUS`

Retrieve all executions for a specific agent with pagination and filtering support. Returns a paginated list of agent execution records including call status, cost breakdown, transcripts, and telephony data.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `to` | string | No | Filter executions where created_at is less than or equal to this UTC datetime (ISO 8601 format) |
| `from` | string | No | Filter executions where created_at is greater than or equal to this UTC datetime (ISO 8601 format) |
| `status` | string | No | Filter by call status (e.g., queued, ringing, completed, failed) |
| `agent_id` | string | Yes | The unique UUID of the agent whose executions you want to retrieve |
| `batch_id` | string | No | Filter executions by specific batch ID |
| `provider` | string | No | Filter by conversation provider (e.g., plivo, twilio, websocket, web-call) |
| `call_type` | string | No | Filter by call type: 'inbound' or 'outbound' |
| `page_size` | integer | No | Number of results per page (maximum: 50, default: 20) |
| `page_number` | integer | No | Page number to retrieve (minimum: 1, default: 1) |
| `answered_by_voice_mail` | boolean | No | Filter by whether the call was answered by voicemail |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Retrieve Batch Details by ID

**Slug:** `BOLNA_RETRIEVE_BATCH_DETAILS_BY_ID`

Retrieve comprehensive details about a specific Bolna batch by its ID. Returns batch metadata including creation time, execution status, scheduled time, contact statistics, and call status breakdown. Use this to monitor batch progress or retrieve information about previously created batch calling campaigns.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `batch_id` | string | Yes | Unique identifier of the batch in 32-character hex format (e.g., '3c90c3cc0d444b5088888dd25736052a') |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Retrieve batch execution list

**Slug:** `BOLNA_RETRIEVE_BATCH_EXECUTION_LIST`

Retrieve all executions from a specific batch with pagination support. Returns detailed information about each call execution including conversation metrics, transcripts, costs, and resource usage breakdown (LLM tokens, synthesizer characters, etc.). Use this to monitor batch campaign results and analyze individual call outcomes.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `batch_id` | string | Yes | The unique identifier of the batch (32-character hex string) |
| `page_size` | integer | No | Number of results per page (maximum 50) |
| `page_number` | integer | No | The page number to retrieve (starts at 1) |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Schedule Batch by ID

**Slug:** `BOLNA_SCHEDULE_BATCH_BY_ID`

Schedule a batch to execute at a specific time. After creating a batch with BOLNA_CREATE_BATCH, use this action to set when the batch calls should begin. The batch must exist and be in a schedulable state (e.g., 'created' or 'stopped').

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `batch_id` | string | Yes | The unique identifier (UUID) of the batch to schedule |
| `scheduled_at` | string | Yes | The scheduled execution time in ISO 8601 format with timezone. Must be a future timestamp specifying when the batch calls should begin. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Search available phone numbers

**Slug:** `BOLNA_SEARCH_PHONE_NUMBERS`

Tool to search for available phone numbers that can be purchased for Bolna Voice agents. Use when you need to find purchasable phone numbers by country or prefix pattern before buying.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `country` | string ("US" | "IN") | Yes | The country code for the phone number. Available options: US or IN |
| `pattern` | string | No | A 3-character prefix for filtering phone numbers during the search |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Setup inbound call for agent

**Slug:** `BOLNA_SETUP_INBOUND_CALL_FOR_AGENT`

Add agent for inbound calls

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | Agent `id` which will handle inbound calls. Used as default if no IVR option-level agent is set. Please make sure that the agent"s Telephony provider is set as Twilio |
| `phone_number_id` | string | Yes | Telephone number `id` from [Phone number list API](/api-reference/phone-numbers/get_all). This is required to associate a phone number with the agent for inbound calls. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Stop Agent Calls

**Slug:** `BOLNA_STOP_AGENT_CALLS`

Tool to stop all queued or scheduled calls for a specific Voice AI agent. Use when you need to immediately halt all pending calls for an agent.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | string | No | Optional user identifier to filter which calls to stop for this agent |
| `agent_id` | string | Yes | Unique identifier (UUID) of the agent whose queued or scheduled calls should be stopped. Obtain this from BOLNA_CREATE_AGENT or BOLNA_GET_ALL_AGENTS. |
| `is_api_request` | boolean | No | Optional flag to indicate if this is an API request. Defaults to false if not provided. |
| `sub_account_id` | string | No | Optional sub-account identifier to filter which calls to stop within a multi-tenant setup |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Stop batch by id

**Slug:** `BOLNA_STOP_BATCH_BY_ID`

Stop a running batch by its ID. This halts all queued calls in the batch. Any calls currently in the queue waiting to be executed will be cancelled and will not be processed. Use this when you need to immediately halt a batch campaign that's in progress.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `batch_id` | string | Yes | The unique identifier (UUID or 32-character hex string) of the batch to stop. Obtain this from BOLNA_CREATE_BATCH or BOLNA_FETCH_ALL_BATCHES_BY_AGENT_ID. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Bolna Voice AI Agent (v2)

**Slug:** `BOLNA_UPDATE_AGENT`

Tool to update all settings and configuration of an existing Bolna Voice AI agent using the v2 API. Use when you need to modify an agent's full configuration including LLM settings, synthesizer, transcriber, tasks, prompts, or any other agent property. This performs a complete update (PUT operation).

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | string | No | Optional user ID parameter for multi-user environments |
| `agent_id` | string | Yes | The unique identifier (UUID) of the agent to update |
| `agent_config` | object | Yes | Complete agent configuration object. Required fields: agent_name (string), agent_type (string: 'other', 'sales', 'support', etc.), agent_welcome_message (string), webhook_url (string URL for callbacks or null), and tasks (array). Each task must include task_type ('conversation', 'extraction', or 'summarization'), toolchain (with execution mode and pipelines), tools_config (defining input/output providers, transcriber, llm_agent, and synthesizer), and task_config (with settings like hangup_after_silence, optimize_latency, etc.). |
| `agent_prompts` | object | Yes | Object containing prompt configurations for each task. Each task key (e.g., 'task_1', 'task_2') maps to an object with a 'system_prompt' string that defines behavioral instructions for that task. |
| `is_api_request` | boolean | No | Flag to indicate if this is an API request. Defaults to false |
| `sub_account_id` | string | No | Optional sub-account ID for multi-tenant scenarios |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |