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.

Custom function configuration modal showing JSON schema with name, description, parameters, and API endpoint 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.

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.

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

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

GET Request - Fetch Product Details

curl --location 'https://my-api-dev.xyz?customer_phone=+19876543210' \
--header 'Authorization: Bearer your_api_token' \
--header 'header1: value1' \
--header 'header2: value2'

The above request corresponds to the following GET custom function:

{
  "name": "get_product_details",
  "description": "Use this tool to fetch product details when the customer asks about products, pricing, or availability.",
  "pre_call_message": "Let me look that up for you.",
  "parameters": {
    "type": "object",
    "properties": {
      "customer_phone": {
        "type": "string",
        "description": "Customer's phone number for verification"
      }
    },
    "required": ["customer_phone"]
  },
  "key": "custom_task",
  "value": {
    "method": "GET",
    "param": {
      "customer_phone": "%(customer_phone)s"
    },
    "url": "https://my-api-dev.xyz",
    "api_token": "Bearer your_api_token",
    "headers": {
      "header1": "value1",
      "header2": "value2"
    }
  }
}

POST Request - Save Customer Feedback

curl --location 'https://my-api-dev.xyz/v1/store_rating' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer your_api_token' \
--header 'version: 1.0' \
--data '{
    "customer_id": "134532",
    "rating": "5",
    "comment": "Great service!"
}'

The above request corresponds to the following POST custom function:

{
  "name": "save_feedback",
  "description": "Use this tool to save customer feedback when they provide a rating, review, or comment about our service.",
  "pre_call_message": "I'm saving your feedback now.",
  "parameters": {
    "type": "object",
    "properties": {
      "customer_id": {
        "type": "string",
        "description": "The customer's unique ID"
      },
      "rating": {
        "type": "string",
        "description": "Rating from 1 to 5"
      },
      "comment": {
        "type": "string",
        "description": "Customer's comment or feedback"
      }
    },
    "required": ["customer_id", "rating"]
  },
  "key": "custom_task",
  "value": {
    "method": "POST",
    "param": {
      "customer_id": "%(customer_id)s",
      "rating": "%(rating)s",
      "comment": "%(comment)s"
    },
    "url": "https://my-api-dev.xyz/v1/store_rating",
    "api_token": "Bearer your_api_token",
    "headers": {
      "Content-Type": "application/json",
      "version": "1.0"
    }
  }
}

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

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

Agent API

Programmatic function configuration

Getting Started

Using Bolna Platform

Pricing

Enterprise

On premise deployments

Multilingual Voice agents

Integrations

Voice AI Agent Function calls

Features

Advance capabilities

Supported Telephony

Phone calls using Bolna

Resources

Custom Function Calls: Complete Guide for Bolna Voice AI

What are Custom Functions?

How Custom Functions Work

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

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

Agent API

Getting Started

Using Bolna Platform

Pricing

Enterprise

On premise deployments

Multilingual Voice agents

Integrations

Voice AI Agent Function calls

Features

Advance capabilities

Supported Telephony

Phone calls using Bolna

Resources

​What are Custom Functions?

​How Custom Functions Work

​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

​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

Agent API

What are Custom Functions?

How Custom Functions Work

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

Best Practices

Troubleshooting

Next Steps