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 — Custom function JSON editor showing a function schema with name, description, pre_call_message, parameters, and API configuration

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 — Add a Custom Tool section showing the Write manually and Generate from cURL options

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 — Custom function JSON editor with a sample schema showing name, description, pre_call_message, parameters, key, and API configuration

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 — Generate function from cURL dialog where you paste a cURL command to auto-generate a custom function

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 — Generated function configuration from a cURL command with auto-populated name, description, URL, and authentication

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

Go deeper

Schema reference

Every field in the function definition and API configuration, plus %(name)s format specifiers.

Examples

Complete GET and POST request schemas you can copy and adapt.

Variables & context

Use prompt variables and auto-injected call data so the agent never asks for what it already knows.

Pre-call webhooks

Notify your system before the tool’s main API call runs, for example with a transfer reason.

Source IP whitelist

Bolna calls your endpoint from a fixed set of source IPs. If your API sits behind a firewall or an IP allowlist, permit all three or the tool call will fail and the agent will have nothing to say back to the caller:

203.39.153
126.9.249
202.133.53

The same IPs apply to pre-call webhooks and to post-call webhooks.

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

Build

Deploy

Monitor

Go live

Custom function calls: Complete guide for Bolna voice AI

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

Go deeper

Schema reference

Examples

Variables & context

Pre-call webhooks

Source IP whitelist

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

Function name

Description

Parameters

Auth & headers

Pre-call message

Context variables

​Go deeper

Schema reference

Examples

Variables & context

Pre-call webhooks

​Source IP whitelist

​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

Go deeper

Source IP whitelist

Best practices

Troubleshooting

Next steps