Custom Functions

Custom functions let your voice agents call external HTTP endpoints mid-conversation. When the agent determines it needs to perform an action — check the weather, book an appointment, look up an order — it invokes a function you’ve defined, waits for the response, and continues the conversation with that data.

How it works

You define a function with a name, description, URL, and input/output schema
You attach it to an agent
During a voice call, the agent’s LLM reads the description and decides when to call it
The bot sends a POST request to your URL with the input parameters
Your endpoint responds with data
The agent uses that data to continue the conversation

User: "What's the weather in Mumbai?"
    ↓
Agent LLM decides to call `get_weather` function
    ↓
Bot says: "Checking the weather..." (random started_message)
    ↓
POST https://your-api.com/weather
Body: { "city": "Mumbai" }
    ↓
Response: { "temperature": 32, "condition": "Sunny" }
    ↓
Agent: "It's currently 32 degrees and sunny in Mumbai!"

Create a function

curl -X POST https://api.vocobase.com/api/v2/functions \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get_weather",
    "description": "Retrieve current weather for a city. Call this when the user asks about weather conditions.",
    "url": "https://api.weather.com/v1/current",
    "headers": [
      { "key": "Authorization", "value": "Bearer weather_api_key_here" }
    ],
    "input_schema": [
      {
        "name": "city",
        "type": "string",
        "description": "City name",
        "required": true
      }
    ],
    "output_schema": [
      {
        "name": "temperature",
        "type": "number",
        "description": "Temperature in Celsius",
        "required": true
      },
      {
        "name": "condition",
        "type": "string",
        "description": "Weather condition (e.g., Sunny, Rainy)",
        "required": true
      }
    ],
    "timeout": 10,
    "started_messages": ["Checking the weather...", "Let me look that up..."],
    "error_message": "Sorry, I could not get the weather right now."
  }'

Response

{
  "success": true,
  "data": {
    "id": "f1234567-abcd-1234-abcd-123456789012",
    "name": "get_weather",
    "description": "Retrieve current weather for a city...",
    "method": "POST",
    "url": "https://api.weather.com/v1/current",
    "header_keys": ["Authorization"],
    "input_schema": [...],
    "output_schema": [...],
    "timeout": 10,
    "started_messages": ["Checking the weather...", "Let me look that up..."],
    "error_message": "Sorry, I could not get the weather right now.",
    "created_at": "2026-04-16T10:30:00Z",
    "updated_at": "2026-04-16T10:30:00Z"
  }
}

Header values are encrypted at rest and never returned by the API. Only header_keys (the key names) appear in responses.

Function fields

Field	Type	Required	Description
`name`	string	Yes	Unique identifier. 1–50 chars, `snake_case` only (lowercase, numbers, underscores). Must start with a letter.
`description`	string	Yes	1–500 chars. This is critical — the LLM reads this to decide when to call the function. Be specific.
`url`	string	Yes	HTTPS endpoint the bot will `POST` to. 1–2000 chars. `localhost` and private IPs are blocked in production.
`headers`	array	No	Up to 10 headers. Each: `{ key: string, value: string }`. Values are encrypted at rest; only key names are returned.
`input_schema`	array	No	Up to 100 fields. Describes what the bot sends in the request body. See Schema fields.
`output_schema`	array	No	Up to 100 fields. Describes the expected response structure. Helps the LLM interpret your API response.
`timeout`	number	No	1–60 seconds. Default: 30. How long the bot waits for your endpoint to respond.
`started_messages`	array	No	Up to 5 strings (max 200 chars each). Bot picks one at random to say while the function executes.
`error_message`	string	No	Max 500 chars. What the bot says if the function fails.

Schema fields

Each entry in input_schema or output_schema:

{
  "name": "city",
  "type": "string",
  "description": "City name to look up",
  "required": true
}

Field	Type	Description
`name`	string	Field name
`type`	string	`string`, `number`, `boolean`, `string[]`, `number[]`, or `custom`
`description`	string	Helps the LLM understand what to pass or expect
`required`	boolean	Whether the field is mandatory
`jsonSchema`	object	Required when `type` is `custom`. A JSON Schema object for complex types.

The description field on the function is the most important part. The LLM uses it to decide when to call the function. Be explicit: “Call this when the user asks about order status” is better than “Get order info”.

Reserved function names

These names are used by built-in integrations and cannot be used: knowledge_base_search, calendar_create_event, calendar_list_events, calendar_update_event, calendar_delete_event, gmail_send_email, gmail_search_emails, slack_send_message, slack_list_channels, add_to_cart, view_cart, clear_cart, checkout

Attach a function to an agent

After creating a function, attach it to one or more agents:

curl -X POST https://api.vocobase.com/api/v2/agent/AGENT_ID/functions/FUNCTION_ID \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"

Response

{
  "success": true,
  "data": { "attached": true }
}

Enable or disable a function for an agent

Functions are enabled by default when attached. Toggle with enabled:

cURL

curl -X PATCH https://api.vocobase.com/api/v2/agent/AGENT_ID/functions/FUNCTION_ID \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

Response

{
  "success": true,
  "data": { "enabled": false }
}

Detach a function from an agent

cURL

curl -X DELETE https://api.vocobase.com/api/v2/agent/AGENT_ID/functions/FUNCTION_ID \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"

Returns 204 No Content on success.

List functions on an agent

See all functions currently active on an agent:

cURL

curl -X GET https://api.vocobase.com/api/v2/agent/AGENT_ID/functions \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"

Response

{
  "success": true,
  "data": {
    "functions": [
      {
        "id": "f1234567-abcd-1234-abcd-123456789012",
        "name": "get_weather",
        "description": "Get weather for a city",
        "method": "POST",
        "url": "https://api.weather.com/v1/current",
        "header_keys": ["Authorization"],
        "input_schema": [...],
        "output_schema": [...],
        "timeout": 10,
        "started_messages": ["Checking the weather..."],
        "error_message": null,
        "enabled": true,
        "created_at": "2026-04-16T10:30:00Z",
        "updated_at": "2026-04-16T10:30:00Z"
      }
    ]
  }
}

Manage functions

List all your functions

cURL

curl -X GET https://api.vocobase.com/api/v2/functions \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"

Get a single function

cURL

curl -X GET https://api.vocobase.com/api/v2/functions/FUNCTION_ID \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"

Update a function

All fields are optional — only provided fields are updated.

cURL

curl -X PUT https://api.vocobase.com/api/v2/functions/FUNCTION_ID \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description for better LLM invocation",
    "timeout": 15
  }'

Delete a function

cURL

curl -X DELETE https://api.vocobase.com/api/v2/functions/FUNCTION_ID \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"

Returns 204 No Content. Deleting a function automatically detaches it from all agents.

Full lifecycle example

# 1. Create the function
FUNC=$(curl -s -X POST https://api.vocobase.com/api/v2/functions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "check_order",
    "description": "Look up order status by order ID. Call when user asks about their order.",
    "url": "https://your-api.com/orders/status",
    "input_schema": [{ "name": "order_id", "type": "string", "description": "Order ID", "required": true }],
    "timeout": 10,
    "started_messages": ["Looking up your order..."]
  }')
FUNCTION_ID=$(echo $FUNC | jq -r '.data.id')

# 2. Attach to agent
curl -X POST "https://api.vocobase.com/api/v2/agent/$AGENT_ID/functions/$FUNCTION_ID" \
  -H "Authorization: Bearer $API_KEY"

# 3. Verify it is active
curl "https://api.vocobase.com/api/v2/agent/$AGENT_ID/functions" \
  -H "Authorization: Bearer $API_KEY"

Building your function endpoint

Your endpoint receives a POST request from the bot with the input fields in the body:

{
  "city": "Mumbai"
}

Respond with a JSON object matching your output_schema:

{
  "temperature": 32,
  "condition": "Sunny"
}

Requirements:

Must respond within the configured timeout (default 30 seconds)
Must return valid JSON
Must return a 2xx status code
HTTPS required in production

If your endpoint fails (timeout, non-2xx, invalid JSON), the bot says the error_message and continues the conversation.

Error responses

Status	Code	Cause
`400`	`VALIDATION_ERROR`	Name format, URL format, schema too large, etc.
`403`	`FUNCTION_LIMIT_REACHED`	Plan limit on number of functions reached
`403`	`FORBIDDEN`	Attempt to modify a built-in function
`404`	`FUNCTION_NOT_FOUND`	Function or agent not found
`409`	`FUNCTION_NAME_TAKEN`	A function with this name already exists
`409`	`ALREADY_ATTACHED`	Function is already attached to this agent

Tips

Write clear descriptions. The description is the #1 factor in whether the agent calls the function at the right time. Include specific trigger phrases: “Call this when the user asks about their order status or delivery date.”

Keep timeouts short. Users are waiting in real-time. A 10-second timeout feels like an eternity in a voice conversation.
Use started_messages. They fill the silence while your endpoint processes. Without them, there is dead air.
One function, many agents. Create a function once and attach it to as many agents as you need.

Custom Functions

Custom Functions

How it works

Create a function

Function fields

Schema fields

Reserved function names

Attach a function to an agent

Enable or disable a function for an agent

Detach a function from an agent

List functions on an agent

Manage functions

List all your functions

Get a single function

Update a function

Delete a function

Full lifecycle example

Building your function endpoint

Error responses

Tips

Next steps

Quick Start

Knowledge Base

Documentation Index

​Custom Functions

​How it works

​Create a function

​Function fields

​Schema fields

​Reserved function names

​Attach a function to an agent

​Enable or disable a function for an agent

​Detach a function from an agent

​List functions on an agent

​Manage functions

​List all your functions

​Get a single function

​Update a function

​Delete a function

​Full lifecycle example

​Building your function endpoint

​Error responses

​Tips

​Next steps

Quick Start

Knowledge Base

Custom Functions

How it works

Create a function

Function fields

Schema fields

Reserved function names

Attach a function to an agent

Enable or disable a function for an agent

Detach a function from an agent

List functions on an agent

Manage functions

List all your functions

Get a single function

Update a function

Delete a function

Full lifecycle example

Building your function endpoint

Error responses

Tips

Next steps