Custom Function Calls: Complete Guide for Bolna Voice AI

What are Custom Functions?

Custom functions let your Voice AI agent call your own APIs during live conversations. Check order status, update a CRM, book appointments, or integrate with any system - all while on a call.

Bolna custom functions follow the OpenAI function calling specification. If you’ve used OpenAI function calling before, you’ll feel right at home.

Bolna custom function configuration modal with dark code editor showing JSON schema with name test, description, pre_call_message, parameters with startTime and endTime, key custom_task, and value with method GET, url, api_token, and headers

How Custom Functions Work

LLM Reads Function Definition

The LLM sees your function’s name and description to understand what the function does

Decides When to Call

Based on conversation context, the LLM decides if this function should be triggered

Extracts Parameters

The LLM collects required parameter values from the conversation with the caller

Bolna Executes API Call

Bolna makes the HTTP request to your API endpoint with the extracted parameters

Response Feeds Back

The API response is returned to the LLM, which continues the conversation naturally

The description is everything. The LLM relies heavily on your description to know when to call the function. A vague description = unreliable triggering.

Creating a Custom Function

You can create a custom function in two ways from the Tools Tab:

Bolna Add a Custom Tool section with Custom Function card showing Write manually button and Generate from cURL button side by side

Write Manually
Generate from cURL

Click Write manually to open the JSON editor and define the function schema from scratch. This gives you full control over every field.

Bolna custom function configuration modal with dark code editor, JSON schema with name test, description, pre_call_message, parameters, key custom_task, and value object with method, url, api_token, and headers

The fields name, description, key, and method are mandatory. The key must always be set to "custom_task".

If you already have a working API request in curl, click Generate from cURL to auto-generate a function schema instead of building it manually.

How to use it

Click Generate from cURL

In the Tools Tab, click the Generate from cURL button under Add a Custom Tool.

Paste your cURL command

Paste the full cURL request into the text area. Bolna will parse the URL, method, headers, and body.

Bolna Generate function from cURL modal with text area containing a sample curl GET request to api.bolna.ai with Authorization Bearer header, Cancel button and Generate function button

Review the generated schema

Bolna generates a function configuration with auto-populated name, description, method, URL, and auth. Review all fields carefully.

Refine and submit

Update the function name, improve the description for better LLM triggering, confirm parameters, and click Submit.

Bolna generated custom function showing name get_agent, description Called when user asks to get agent details by agent ID, pre_call_message, parameters, key custom_task, method GET, url api.bolna.ai, api_token, and headers

The import is a starting point, not a final configuration. Always verify authentication, parameter names, required fields, and the API URL before using the function in production.

After generating, always check

Function name

Make it clear and use snake_case (e.g., get_order_status)

Description

Describe when the model should call the function, not just what the API does

Parameters

Remove anything the caller will never provide; mark only essential fields as required

Auth & headers

Confirm secrets, tokens, and custom headers are correct for your environment

Pre-call message

Add a short spoken message so callers know the agent is checking something

Context variables

Combine with context variables to avoid asking for data you already have

Complete Schema Structure

Every custom function has two parts: Function Definition (tells LLM what it does) and API Configuration (tells Bolna how to call your API).

{
  "name": "function_name",
  "description": "Detailed description of when to call this function",
  "pre_call_message": "What agent says while the API is being called",
  "parameters": {
    "type": "object",
    "properties": {
      "param_name": {
        "type": "string",
        "description": "What this parameter represents"
      }
    },
    "required": ["param_name"]
  },
  "key": "custom_task",
  "value": {
    "method": "GET",
    "param": {
      "param_name": "%(param_name)s"
    },
    "url": "https://your-api.com/endpoint",
    "api_token": "Bearer your_token",
    "headers": {}
  }
}

Mandatory: The field "key": "custom_task" must be present exactly as shown. Do not modify this value.

Schema Reference

Parts 1-2 follow the OpenAI function calling specification - they define what the function does. Parts 3-5 are Bolna extensions that define how to execute the API call automatically.

Function Definition
Parameters Object
Bolna Extensions
API Configuration
Format Specifiers

1. Function Definition

These fields tell the LLM about your function:

Field	Required	Description
`name`	Yes	Unique function identifier. Use `snake_case` (e.g., `get_order_status`)
`description`	Yes	Tells the LLM when to trigger this function. Be specific and detailed.
`parameters`	Yes	Defines what information to collect from the caller

2. Parameters Object

The parameters object defines what information the LLM should collect from the caller.

"parameters": {
  "type": "object",
  "properties": {
    "customer_name": {
      "type": "string",
      "description": "The customer's full name"
    },
    "order_id": {
      "type": "string",
      "description": "The order ID, usually starts with ORD-"
    },
    "quantity": {
      "type": "integer",
      "description": "Number of items"
    }
  },
  "required": ["customer_name", "order_id"]
}

Supported Data Types:

Type	Use Case	Example Values
`string`	Text, names, IDs, phone numbers	`"John Doe"`, `"ORD-12345"`
`integer`	Whole numbers	`5`, `100`, `-10`
`number`	Decimal numbers	`29.99`, `3.14`
`boolean`	True/false flags	`true`, `false`

Required vs Optional:

In `required` array?	Behavior
Yes	LLM will keep asking until this value is provided
No	Optional - included if mentioned, skipped otherwise

3. Bolna Extensions

These fields are specific to Bolna:

Field	Required	Description
`pre_call_message`	No	Message the agent speaks while API is executing (e.g., “One moment please…”)
`key`	Yes	Must be `"custom_task"` - identifies this as a custom function
`value`	Yes	API configuration object (see below)

4. API Configuration (`value` object)

This tells Bolna how to make the HTTP request:

Field	Required	Description
`method`	Yes	HTTP method: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`
`url`	Yes	Your API endpoint URL
`param`	Yes	Maps parameters to API request using format specifiers
`api_token`	No	Authorization header value (e.g., `Bearer your_token`)
`headers`	No	Additional HTTP headers as key-value pairs
`pre_call_webhook_param`	No	Body template for a pre-call webhook that fires before the main API call. This is the on/off switch — if it is not set, no pre-call webhook fires.
`pre_call_webhook_url`	No	Where to send the pre-call webhook. If omitted, the agent-level Webhook URL is used. See Pre-call Webhooks.

5. Format Specifiers

The param object maps your parameters to the API request. Use Python-style format specifiers:

Data Type	Format Specifier	Example
String	`%(param_name)s`	`"customer_id": "%(customer_id)s"`
Integer	`%(param_name)i`	`"quantity": "%(quantity)i"`
Float	`%(param_name)f`	`"price": "%(price)f"`

Parameter names must match exactly. The name in properties must be identical to the name in param mapping (case-sensitive).

Examples

The following examples use illustrative endpoints and credentials to demonstrate the schema structure. Replace the URLs, tokens, and parameter values with your own API details when implementing.

GET Requests
POST Requests

Check Order Status

A customer calls and asks “Where is my order?” The agent collects the order ID and fetches the status from your backend.What the agent says: “Let me check the status of your order.”What Bolna sends:

curl --location 'https://api.yourstore.com/orders?order_id=ORD-78234' \
--header 'Authorization: Bearer sk_live_abc123'

Function schema:

{
  "name": "check_order_status",
  "description": "Use this function when the customer asks about their order status, delivery update, shipping progress, or tracking information. The customer must provide their order ID.",
  "pre_call_message": "Let me check the status of your order.",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "The customer's order ID. Usually starts with ORD- followed by numbers, e.g., ORD-78234."
      }
    },
    "required": ["order_id"]
  },
  "key": "custom_task",
  "value": {
    "method": "GET",
    "param": {
      "order_id": "%(order_id)s"
    },
    "url": "https://api.yourstore.com/orders",
    "api_token": "Bearer sk_live_abc123",
    "headers": {}
  }
}

Example API response the LLM receives:

{
  "order_id": "ORD-78234",
  "status": "shipped",
  "estimated_delivery": "March 15, 2026",
  "tracking_number": "1Z999AA10123456784"
}

The agent would then say something like: “Your order ORD-78234 has been shipped and is expected to arrive by March 15th. Your tracking number is 1Z999AA10123456784.”

Look Up Account Balance

A customer calls and asks “What’s my current balance?” The agent verifies their identity using their registered phone number and account ID, then fetches the balance.What the agent says: “Let me pull up your account details.”What Bolna sends:

curl --location 'https://api.yourbank.com/accounts/balance?account_id=ACC-991042&phone=%2B919876543210' \
--header 'Authorization: Bearer fin_api_key_001' \
--header 'X-Request-Source: voice-agent'

Function schema:

{
  "name": "get_account_balance",
  "description": "Use this function when the customer asks about their account balance, available credit, remaining amount, or account summary. Requires the customer's account ID and phone number for verification.",
  "pre_call_message": "Let me pull up your account details.",
  "parameters": {
    "type": "object",
    "properties": {
      "account_id": {
        "type": "string",
        "description": "The customer's account ID, usually starts with ACC- followed by numbers."
      },
      "phone": {
        "type": "string",
        "description": "The customer's registered phone number for identity verification."
      }
    },
    "required": ["account_id", "phone"]
  },
  "key": "custom_task",
  "value": {
    "method": "GET",
    "param": {
      "account_id": "%(account_id)s",
      "phone": "%(phone)s"
    },
    "url": "https://api.yourbank.com/accounts/balance",
    "api_token": "Bearer fin_api_key_001",
    "headers": {
      "X-Request-Source": "voice-agent"
    }
  }
}

Example API response the LLM receives:

{
  "account_id": "ACC-991042",
  "name": "Rahul Verma",
  "current_balance": 24500.75,
  "currency": "INR",
  "last_transaction": "2026-03-12"
}

The agent would then say something like: “Your current account balance is Rs. 24,500.75. Your last transaction was on March 12th.”

The phone parameter can be auto-injected using the {from_number} context variable, so the caller does not need to repeat their number.

Book an Appointment

A caller wants to schedule a consultation. The agent collects their name, preferred date, and time, then creates the booking.What the agent says: “I’m booking that appointment for you now.”What Bolna sends:

curl --location 'https://api.yourclinic.com/v1/appointments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer clinic_token_xyz' \
--data '{
    "patient_name": "Priya Sharma",
    "preferred_date": "2026-03-20",
    "preferred_time": "10:30 AM",
    "reason": "General consultation"
}'

Function schema:

{
  "name": "book_appointment",
  "description": "Use this function when the caller wants to book, schedule, or set up an appointment, consultation, or visit. Collect the patient's name, their preferred date and time, and the reason for the visit.",
  "pre_call_message": "I'm booking that appointment for you now.",
  "parameters": {
    "type": "object",
    "properties": {
      "patient_name": {
        "type": "string",
        "description": "Full name of the patient"
      },
      "preferred_date": {
        "type": "string",
        "description": "Preferred appointment date in YYYY-MM-DD format"
      },
      "preferred_time": {
        "type": "string",
        "description": "Preferred time, e.g., '10:30 AM' or '2:00 PM'"
      },
      "reason": {
        "type": "string",
        "description": "Brief reason for the appointment, e.g., 'General consultation' or 'Follow-up'"
      }
    },
    "required": ["patient_name", "preferred_date", "preferred_time"]
  },
  "key": "custom_task",
  "value": {
    "method": "POST",
    "param": {
      "patient_name": "%(patient_name)s",
      "preferred_date": "%(preferred_date)s",
      "preferred_time": "%(preferred_time)s",
      "reason": "%(reason)s"
    },
    "url": "https://api.yourclinic.com/v1/appointments",
    "api_token": "Bearer clinic_token_xyz",
    "headers": {
      "Content-Type": "application/json"
    }
  }
}

The reason field is optional (not in the required array). If the caller mentions a reason, the LLM includes it. If not, it is skipped without asking.

Create a Support Ticket

A customer calls with a complaint or issue. The agent collects the details and creates a support ticket in your helpdesk system.What the agent says: “I’m creating a support ticket for this issue right away.”What Bolna sends:

curl --location 'https://api.yourhelpdesk.com/tickets' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer helpdesk_key_789' \
--data '{
    "caller_phone": "+919876543210",
    "issue_category": "billing",
    "description": "Customer was charged twice for their February subscription",
    "priority": "high"
}'

Function schema:

{
  "name": "create_support_ticket",
  "description": "Use this function when the customer reports a problem, complaint, issue, or bug. Create a support ticket with the issue category, a summary of the problem, and priority level. The caller's phone number is automatically available.",
  "pre_call_message": "I'm creating a support ticket for this issue right away.",
  "parameters": {
    "type": "object",
    "properties": {
      "caller_phone": {
        "type": "string",
        "description": "The customer's phone number"
      },
      "issue_category": {
        "type": "string",
        "description": "Category of the issue: billing, technical, account, shipping, or other"
      },
      "description": {
        "type": "string",
        "description": "A brief summary of the customer's issue in 1-2 sentences"
      },
      "priority": {
        "type": "string",
        "description": "Priority level: low, medium, or high. Set to high if the customer is upset or the issue is time-sensitive."
      }
    },
    "required": ["caller_phone", "issue_category", "description"]
  },
  "key": "custom_task",
  "value": {
    "method": "POST",
    "param": {
      "caller_phone": "%(caller_phone)s",
      "issue_category": "%(issue_category)s",
      "description": "%(description)s",
      "priority": "%(priority)s"
    },
    "url": "https://api.yourhelpdesk.com/tickets",
    "api_token": "Bearer helpdesk_key_789",
    "headers": {
      "Content-Type": "application/json"
    }
  }
}

The caller_phone can be auto-injected using context variables. Add {from_number} to your agent prompt, and the LLM will use it automatically instead of asking the caller for their number.

Using Variables and Dynamic Context

Context variables defined in your agent prompt are automatically substituted into custom functions. The LLM won’t ask the caller for these values - they’re already available.

Auto-Injected System Variables

Variable	Description
`{agent_id}`	The `id` of the agent
`{call_sid}`	Unique `id` of the phone call (from Twilio, Plivo, etc.)
`{from_number}`	Phone number that initiated the call
`{to_number}`	Phone number that received the call

How Variable Substitution Works

You are agent Sam speaking to {customer_name}.
The agent ID is "{agent_id}".
The call ID is "{call_sid}".
The customer's phone is "{to_number}".

Parameter	Defined in Prompt?	Result
`to_number`	Yes (system)	Auto-substituted
`agent_id`	Yes (system)	Auto-substituted
`customer_name`	Yes (passed via call)	Auto-substituted
`customer_address`	No	LLM will collect from caller

Pre-call Webhooks

A custom function can fire a pre-call webhook — a notification sent to a URL of your choice before the tool’s main API call runs. A common use case is a tool that transfers the call, where your system needs to receive the transfer reason before the transfer happens.

The pre-call webhook is fire-and-forget. A slow or failing webhook endpoint never blocks or fails the function call itself.

How It Works

LLM decides to call the tool

The LLM produces the arguments for your custom function as usual.

Bolna fires the pre-call webhook

If the tool has a pre_call_webhook_param configured, Bolna first POSTs the pre-call webhook to the resolved URL.

The main API call runs

The tool’s main function call then executes exactly as it normally would.

Configuring the Webhook Body

pre_call_webhook_param is a JSON template that is completely independent from the tool’s main param. You can reference any argument the LLM produced for the tool using the same %(field)s substitution syntax used by param. Static values are passed through as-is.

{
  "name": "transfer_support",
  "description": "Transfers the call to a support agent when the caller asks for a human or has an issue the agent cannot resolve.",
  "parameters": {
    "type": "object",
    "properties": {
      "reason": {
        "type": "string",
        "description": "Why the caller wants a transfer"
      }
    },
    "required": ["reason"]
  },
  "key": "custom_task",
  "value": {
    "method": "POST",
    "url": "https://your-api.com/transfer",
    "param": {
      "reason": "%(reason)s"
    },
    "pre_call_webhook_url": "https://your-api.com/pre-transfer-hook",
    "pre_call_webhook_param": {
      "transfer_reason": "%(reason)s",
      "channel": "voice"
    }
  }
}

In the example above, %(reason)s is replaced with the LLM’s argument for this tool call, while "channel": "voice" is a static value passed through unchanged.

What Your Endpoint Receives

The webhook body is the same execution record you receive on the post-call execution webhook (execution id, agent id, telephony details, status, etc.), merged with the fields from your pre_call_webhook_param:

{
  "id": "<execution_id>",
  "agent_id": "<agent_id>",
  "status": "in-progress",
  "telephony_data": { "...": "..." },
  "...": "...",

  "transfer_reason": "customer asked for billing",
  "channel": "voice"
}

Because the call is still in progress when the pre-call webhook fires, fields that are only finalized at call end (transcript, cost, summary) won’t be complete yet.

URL Resolution Rules

`pre_call_webhook_param`	`pre_call_webhook_url`	Result
Set	Set	Webhook sent to the tool’s `pre_call_webhook_url`.
Set	Not set	Webhook sent to the agent-level Webhook URL (the same URL used for post-call execution webhooks).
Not set	Set or not set	No pre-call webhook fires.

pre_call_webhook_param is the master switch. If it is not set, no pre-call webhook fires — even if pre_call_webhook_url is configured. The agent’s normal post-call webhook is unaffected.

Agent-level URL fallback: when pre_call_webhook_param is set without a pre_call_webhook_url, the pre-call webhook is sent to your agent’s configured Webhook URL. If you already use that endpoint for post-call execution webhooks, it will now also receive pre-call webhooks. Distinguish them by the in-progress status and the extra fields from your pre_call_webhook_param.

UI Configuration

In the agent dashboard, the custom tool configuration (on the Tools Tab) has two optional inputs that map to these fields:

Pre-call webhook URL — the endpoint to notify (pre_call_webhook_url).
Pre-call webhook parameters — the JSON body template with %(field)s substitution (pre_call_webhook_param).

Both save with the tool and round-trip on edit.

Best Practices

Write Detailed Descriptions

Include synonyms and variations: “Use when customer asks about order status, shipping, delivery, or tracking”

Always Add Pre-call Message

Set a friendly message like “Let me check that for you” so callers know to wait

Use Required Fields Wisely

Only mark parameters as required if the function truly cannot work without them

Test APIs First

Verify your API works with tools like curl or Postman before adding to Bolna

Leverage Auto-Injection

Put known data in the agent prompt to avoid asking callers for information you already have

Match Names Exactly

Parameter names in properties and param must be identical (case-sensitive)

Troubleshooting

Function not being triggered

Cause: Description doesn’t match what the caller is saying.Fix: Make your description more comprehensive. Include synonyms and example phrases.

API returns error

Cause: Incorrect URL, authentication, or headers.Fix: Test your API with curl or Postman first. Verify api_token format and required headers.

Parameters not being passed correctly

Cause: Typo or format specifier mismatch.Fix: Ensure parameter names match exactly between properties and param. Use %(name)s format.

Variables not being substituted

Cause: Variable not defined in agent prompt.Fix: Add the variable to your agent prompt using {variable_name} syntax.

Next Steps

Context Variables

Learn about dynamic variable injection

Transfer Calls

Route calls to human agents

Calendar Integration

Book appointments via Cal.com

Using Webhooks

Receive execution data, including pre-call webhooks

Agent API

Programmatic function configuration

​What are Custom Functions?

​How Custom Functions Work

​Creating a Custom Function

​How to use it

​After generating, always check

Function name

Description

Parameters

Auth & headers

Pre-call message

Context variables

​Complete Schema Structure

​Schema Reference

​1. Function Definition

​2. Parameters Object

​3. Bolna Extensions

​4. API Configuration (value object)

​5. Format Specifiers

​Examples

​Using Variables and Dynamic Context

​Auto-Injected System Variables

​How Variable Substitution Works

​Pre-call Webhooks

​How It Works

​Configuring the Webhook Body

​What Your Endpoint Receives

​URL Resolution Rules

​UI Configuration

​Best Practices

Write Detailed Descriptions

Always Add Pre-call Message

Use Required Fields Wisely

Test APIs First

Leverage Auto-Injection

Match Names Exactly

​Troubleshooting

​Next Steps

Context Variables

Transfer Calls

Calendar Integration

Using Webhooks

Agent API

What are Custom Functions?

How Custom Functions Work

Creating a Custom Function

How to use it

After generating, always check

Complete Schema Structure

Schema Reference

1. Function Definition

2. Parameters Object

3. Bolna Extensions

4. API Configuration (`value` object)

5. Format Specifiers

Examples

Using Variables and Dynamic Context

Auto-Injected System Variables

How Variable Substitution Works

Pre-call Webhooks

How It Works

Configuring the Webhook Body

What Your Endpoint Receives

URL Resolution Rules

UI Configuration

Best Practices

Troubleshooting

Next Steps