Custom function schema reference

This page documents every field of a custom function. For a walkthrough of creating one in the dashboard, start there.

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).

Build

Deploy

Monitor

Go live

Custom function schema reference

Complete schema structure

Schema reference

1. Function Definition

2. Parameters Object

3. Bolna Extensions

4. API Configuration (`value` object)

5. Format Specifiers

​Complete schema structure

​Schema reference

​1. Function Definition

​2. Parameters Object

​3. Bolna Extensions

​4. API Configuration (value object)

​5. Format Specifiers

Complete schema structure

Schema reference

1. Function Definition

2. Parameters Object

3. Bolna Extensions

4. API Configuration (`value` object)

5. Format Specifiers