Function Call Agent Actions

During the conversation with a caller, you can configure your agent to perform certain actions at the request of the caller. This is done by configuring the various function calls available. This guide covers how to define and customize function calls for your AI agent. This Function Call feature is displayed on the Platform dashboard alongside the Custom Prompt feature.

Quick Overview

End Call

Cost: Free
Customisable Aspects:

Transition message

Transfer Call

Cost: 10 credits, 40 credits per minute of the transferred call
Customisable Aspects:

Transition message.
Display Agent’s or caller’s number to transferee.
Warm transfer or Cold.
List of transferrable contacts.

Custom Function Call

Cost: Free
Customisable Aspects:

Transition message
Function prompt description
External API Integration
Authentication Methods
Request/Response Processing
Error Handling & Retries

GCal — Check Availability

Cost: Free
Requires: Google Calendar integration connected at the workspace level
Customisable Aspects:

Transition message
Calendars to check (multi-select picker)
Slot duration, look-ahead window, minimum notice
Max number of slots to offer
Default timezone

End Call

End Call is a simple function call in which the Agent intelligently determines when to end the call based on the conversation with the caller. It’s free of cost and available for all agents.

Transition Message

Users can customize the goodbye message that the Agent delivers to the caller before ending the call.

Transfer Call

The Transfer Call function allows the agent to transfer the call to another number, at the request of the caller. It is available for all agents. Each Transfer Call request is charged at a cost of 10 credits. Once the transferred call is in progress, it will be charged at a rate of 40 credits per minute, independently from the initial AI call.

Transition Message

Custom message the Agent delivers to the caller before attempting to transfer the call to the desired transferee.

Display Agent Caller ID

Whether the transferree should see the Agent’s phone number or the caller’s phone number in the dialled call.

Warm vs Cold Transfer

Select between either Warm or Cold transfer. Warm transfer allows the transferree to hear a summary of the previous AI call whilst the call is still connecting. This way the transferree can be provided some context of the previous call. Cold transfer has no summary of the previous call.

Transferrable Contacts

A list of contacts the agents can transfer the call to. The contacts are mapped between name and number The agent can use the name in the conversation to help caller identify whom they wish to transfer the call to.

The numbers must entered in E.164 format, and we only support Australian numbers at the moment. I.e. +614XXXXXXXX for mobile, or +61XYYYYYYYY for landline where X is not 4.

Custom Function Call

The Custom Function Call feature enables your AI agent to dynamically call external APIs during conversations, allowing it to fetch real-time data, perform actions, or integrate with third-party services. This powerful capability transforms your agent from a static conversational AI into a dynamic, action-oriented assistant.

Key Features

Dynamic API Integration: Connect to any REST API endpoint
Multiple Authentication Methods: Support for API keys, Bearer tokens, Basic auth, and webhook secrets
Intelligent Parameter Mapping: Automatic URL templating and parameter substitution
Response Processing: Extract and structure data from API responses
Error Handling: Configurable retry logic and error mapping
Secure Credential Storage: Encrypted storage of sensitive API keys and passwords

Configuration Overview

Function Configuration

Function Name

A unique identifier for your custom function (e.g., get_weather_forecast, fetch_github_profile). This name is used by the AI agent to identify and call the appropriate function during conversations.

Function Description

A clear, detailed description of what the function does. Include relevant keywords to help the AI agent understand when to use this function:

"Retrieve weather forecast and climate data for specific locations and dates. Use this function when the caller asks about weather conditions, temperature, or climate information."

Parameter Specification

Define the input parameters your function accepts using JSON Schema format, abiding by OpenAPI Specification:

Additionally refer to OpenAI’s cookbook for an easy-to-follow example.

{
  "location": {
    "type": "string",
    "description": "The city, state, or location for weather forecast (e.g., 'Sydney, NSW')",
    "required": true,
    "minLength": 2,
    "maxLength": 100
  },
  "start_date": {
    "type": "string",
    "description": "Start date for weather forecast in YYYY-MM-DD format. For single day requests, use the same date as end_date. For multiple days, use the earliest requested date to create an optimal date range.",
    "format": "date",
    "required": true,
  },
  "end_date": {
    "type": "string",
    "description": "End date for weather forecast in YYYY-MM-DD format. For single day requests, use the same date as start_date. For multiple days, use the latest requested date to create an optimal date range that covers all requested days.",
    "format": "date",
    "required": true,
  },
  "unitGroup": {
    "type": "string",
    "required": false,
    "default": "metric",
    "enum": ["metric", "us", "uk"],
    "description": "Temperature unit system"
  },
  "include": {
    "type": "string",
    "required": false,
    "default": "days",
    "enum": ["days", "hours", "current"],
    "description": "Data granularity level"
  }
}

API Configuration

API Endpoint

The URL endpoint for your external API. Supports parameter templating using {parameter_name} syntax:

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/{location}/{start_date}/{end_date}

HTTP Method

Select the appropriate HTTP method for your API (GET, POST, PUT, PATCH, DELETE).

Timeout

Maximum time (in seconds) to wait for the API response before timing out (default: 30 seconds).

Authentication Methods

Custom Function Call supports four authentication methods to accommodate different API security requirements:

1. API Key Authentication

Use for APIs that require an API key in headers or query parameters. Configuration:

API Key: Your authentication key (include prefix if required, e.g., Bearer your_key or token your_key)
Header Name: Custom header name (e.g., Authorization, X-API-Key)
Query Parameter Name: Query parameter name (e.g., key, api_key)

Examples:

# GitHub API (Header)
Authorization: Bearer ghp_your_token_here

# Weather API (Query Parameter)  
https://api.weather.com/forecast?location=sydney&key=your_api_key

# Custom Header
X-API-Key: your_api_key_here

2. Bearer Token Authentication

Standard OAuth2 Bearer token authentication. Configuration:

Bearer Token: Your OAuth2 access token

Example:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

3. Basic Authentication

HTTP Basic authentication using username and password. Configuration:

Username: Your API username
Password: Your API password

Credentials are automatically base64 encoded and prefixed with “Basic ” in the Authorization header. Additionally password is also hashed when stored, for security reasons.

4. Webhook Secret Authentication

For APIs that require webhook signature verification. Configuration:

Webhook Secret: Your webhook signing secret
Event Type: Custom event type (default: voqo.custom_function_call)

We only support POST requests for webhook authentication.

Response Processing

Response Extraction

Map API response fields to variables, via simple path dot notation, that can be used in the conversation:

{
  "location": "resolvedAddress",
  "first_day_temp": "days[0].temperature",
  "all_days_max_temp": "days[*].tempmax"
}

Path Syntax:

Simple paths: current.temperature
Array access: forecast[0].date
Wildcard arrays: forecast[*].tempMax

Error Mapping

Map API error responses to user-friendly messages:

{
  "401": "Request failed due to system error, I will notify my boss about this. Sorry for the inconvenience.",
  "429": "You've made too many of these requests in a short period of time. Please try again later."
}

Retry Configuration

Configure automatic retry behavior for failed API calls:

Max Attempts: Maximum number of retry attempts (default: 3)
Initial Delay: Starting delay between retries in seconds (default: 1.0)
Max Delay: Maximum delay between retries in seconds (default: 10.0)
Backoff Factor: Multiplier to increase delay between retries (default: 2.0)

Security & Best Practices

Credential Security

All secrets (API keys, passwords, webhook secrets) are encrypted at rest.
Secrets are never stored in plain text.
Secrets are automatically masked in the UI for security.

API Key Prefixes

When using API Key authentication, include any required prefixes in the API key field:

GitHub: Bearer ghp_your_token_here
Some APIs: token your_token_here
Simple APIs: your_key_here (no prefix)

Rate Limiting

Implement appropriate timeout values to avoid API rate limits
Use retry configuration with exponential backoff for transient failures
Consider API usage limits when designing function calls

Example Configurations

Weather API GET Request

{
  "transition_message": "grabbing climate info, please wait",
  "function_name": "get_weather_forecast",
  "function_description": "Retrieve weather forecast and climate data for specific locations and dates. Keywords: weather, forecast, temperature, climate, precipitation, rain, sunny, cold, hot, atmospheric, humidity, wind. Use this function ONLY when the caller asks about weather conditions, temperature, precipitation, climate, or atmospheric conditions for a specific location and date range. Requires location, start_date, and end_date parameters.",
  "parameter_specification": {
    "location": {
      "type": "string",
      "required": true,
      "description": "The city, state, or location for weather forecast (e.g., 'San Francisco, CA')",
      "minLength": 2,
      "maxLength": 100
    },
    "start_date": {
      "type": "string",
      "format": "date",
      "required": true,
      "description": "Start date for weather forecast in YYYY-MM-DD format. For single day requests, use the same date as end_date. For multiple days, use the earliest requested date to create an optimal date range."
    },
    "end_date": {
      "type": "string",
      "format": "date",
      "required": true,
      "description": "End date for weather forecast in YYYY-MM-DD format. For single day requests, use the same date as start_date. For multiple days, use the latest requested date to create an optimal date range that covers all requested days."
    },
    "unitGroup": {
      "type": "string",
      "required": false,
      "default": "metric",
      "enum": ["metric", "us", "uk"],
      "description": "Temperature unit system"
    },
    "include": {
      "type": "string",
      "required": false,
      "default": "days",
      "enum": ["days", "hours", "current"],
      "description": "Data granularity level"
    }
  },
  "api_endpoint": "https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/{location}/{start_date}/{end_date}",
  "api_method": "GET",
  "auth": {
    "type": "api_key",
    "api_key": "your_api_key",
    "query_param_name": "key",
  },
  "headers": {},
  "timeout": "30",
  "retry_config": {
    "max_attempts": 3,
    "initial_delay": 1.0,
    "max_delay": 10.0,
    "backoff_factor": 2.0
  },
  "response_status_processing": {
    "success_criteria": {},
    "error_mapping": {}
  },
  "response_extraction": {
    "location": "resolvedAddress",
    "all_daily_tempmax_data": "days[*].tempmax",
    "all_daily_tempmin_data": "days[*].tempmin"
  }
},

GitHub API GET user info Request

{
  "function_name": "fetch_github_profile", 
  "function_description": "Retrieve GitHub user profile public information",
  "api_endpoint": "https://api.github.com/users/{username}",
  "api_method": "GET",
  "auth": {
    "type": "bearer",
    "api_key": "ghp_your_github_token_here"
  },
  "headers": {},
  "timeout": "30",
  "retry_config": {
    "max_attempts": 3,
    "initial_delay": 1.0,
    "max_delay": 10.0,
    "backoff_factor": 2.0
  },
  "parameter_specification": {
    "username": {
      "type": "string",
      "required": true,
      "description": "The username of the GitHub user to fetch profile information for"
    }
  },
  "response_status_processing": {
    "success_criteria": {},
    "error_mapping": {}
  },
  "response_extraction": {}
}

Usage in Conversations

Once configured, your AI agent will automatically identify when to use custom functions based on the caller’s requests: Caller: “What’s the weather like in Sydney next weekend?” Agent: “Let me check the forecast for you…” [Agent calls get_weather_forecast function with next Saturday and Sunday as the date range, and other parameters if applicable (inclu. humidity in this example), then processes and returns the following response] Agent: “The temperature in Sydney next Saturday is 22°C with partly cloudy skies and 65% humidity, and the temperature on Sunday is 25°C with sunny skies and 50% humidity.”

The quality of the Agent’s ability to use the custom function call is dependent on the custom function call’s configuration, especially the prompting in the description fields (function description and parameter specification).

Troubleshooting

Common Issues

Authentication Errors (401)
- Verify API key/token is correct and not expired
- Check if prefix is required (e.g., Bearer for GitHub)
- Ensure credentials are properly encrypted and stored
Parameter Mapping Errors
- Verify JSON Schema syntax is valid
- Check that required parameters are properly defined
- Ensure parameter names match URL template placeholders
Response Processing Issues
- Validate response extraction paths match actual API response structure
- Test API endpoint directly to understand response format
- Check for nested objects and array structures
Timeout Errors
- Increase timeout value for slow APIs
- Implement retry configuration for transient failures
- Consider API rate limits and usage patterns

Debug Information

Enable debug logging to troubleshoot function call issues:

Check terminal logs for API request/response details
Verify authentication headers are correctly formatted
Monitor retry attempts and error responses

Cost & Limitations

Cost: Free for all agents
Rate Limits: Subject to your API provider’s rate limits
Timeout: Maximum 60 seconds per API call
Response Size: No hard limit, but recommended to define specific Response Variables for key info extraction to avoid bloating Agent memory.
Concurrent Calls: Not applicable, we only allow sequential function calls (one at a time) for now.

GCal — Check Availability

The GCal Check Availability function lets your agent read your Google Calendar(s) mid-call and offer the caller concrete open slots. The agent confirms the slot verbally — your team books it manually afterwards. It’s currently the only Google Calendar function-call action — booking (writing events directly from a call) is on the roadmap. It’s free and available for every agent in a workspace that has Google Calendar connected.

This function call is integration-backed — it only appears in the function-call picker when Google Calendar is connected at the workspace level. Disconnect Google Calendar and the action silently drops out of every agent that uses it on the next call. For the full integration story, see the Google Calendar integration docs.

Two calendar selections, two scopes. The Calendars you pick here apply to this agent’s availability checks. Your workspace’s AI assistant (“what’s on my plate”) has its own, separate calendar selection, set on the Google Calendar card under ⋮ → Choose calendars — see choosing calendars for your AI assistant. Both selections accept multiple calendars.

Prerequisites

Google Calendar integration connected for the workspace (see setup)
Workspace’s connected Google account has access to the calendars you want the agent to read

Configuration

Field	What it does	Recommended starting point
Calendars	Which calendars to check. A multi-select dropdown shows every calendar your connected Google account can see — pick one or more.	Primary (your main calendar)
Slot duration (minutes)	How long each proposed slot should be.	30 (or 15 for quick callbacks, 60 for inspections)
Look-ahead (minutes)	How far into the future to search for free slots.	7200 (5 days)
Minimum notice (minutes)	Don’t propose slots starting within this many minutes from now.	60 (don’t propose slots within the next hour)
Max slots	The maximum number of options the agent will read out.	5 (more than this is overwhelming on a call)
Default timezone	IANA timezone, e.g. `Australia/Sydney`. The agent uses this when the caller doesn’t specify a timezone.	Your office’s timezone
Transition message	A short phrase the agent says before checking the calendar — fills the silence during the lookup.	”Let me check the calendar for you…”

What the caller hears

Caller: “When can I come and see the property?” Agent: “Let me check the calendar for you…” [Agent calls Google Calendar’s freeBusy endpoint for the selected calendars and time window, finds open slots that match the configured duration and notice constraints, then reads them back.] Agent: “I’ve got three options that work: Thursday at 10 AM, Thursday at 2 PM, or Friday at 9 AM. Which suits you?” Caller: “Thursday at 2 PM works.” Agent: “Great — I’ll note that down and someone from our team will confirm with you shortly.”

Common configurations

Inspection requests

Slot duration 60 minutes, look-ahead 48 hours, max slots 3
Default timezone matches the property’s location

Vendor catch-up calls

Slot duration 15 minutes, look-ahead 5 days, max slots 5
Useful for callers who want a short check-in this week

Sales colleague handovers

Add the colleague’s shared calendar to the Calendars dropdown (the colleague needs to share their calendar with your connected Google account first)
Slot duration matches the colleague’s typical call length

Failure handling

Failure	What the caller hears	What you do
Google Calendar is disconnected at call time	Agent doesn’t offer the availability check at all (action silently drops out)	Reconnect from the Integrations page
`freeBusy` API timeout or transient error	”I can’t check the calendar right now”	Usually transient — try again. If persistent, contact support
No slots found in the look-ahead window	Agent says it can’t find any open times that match	Increase look-ahead, reduce minimum notice, or check that the selected calendar(s) actually have free windows
Selected calendar no longer exists in Google	Skipped silently for that calendar; others still checked	Re-open the action config — the picker refreshes from Google and you can remove the dead calendar

Cost & limitations

Cost: Free for all agents (no Google Calendar API charges either — we operate within Google’s free tier for the volumes in scope)
Read-only: v1.0 ships availability lookups only. Writing events (locking the booking in directly from the call) is on the roadmap
Read-only at the OAuth scope level too: Voqo only requests calendar.readonly — we cannot create, modify, or delete anything on your calendar in v1.0
No background syncing: Voqo reads your calendar live each call. Nothing is cached on our side

For the full integration story (OAuth flow, what other Voqo AI surfaces will use this connection, troubleshooting), see the Google Calendar overview.

​Quick Overview

End Call

Transfer Call

Custom Function Call

GCal — Check Availability

​End Call

​Transition Message

​Transfer Call

​Transition Message

​Display Agent Caller ID

​Warm vs Cold Transfer

​Transferrable Contacts

​Custom Function Call

​Key Features

​Configuration Overview

​Function Configuration

​Function Name

​Function Description

​Parameter Specification

​API Configuration

​API Endpoint

​HTTP Method

​Timeout

​Authentication Methods

​1. API Key Authentication

​2. Bearer Token Authentication

​3. Basic Authentication

​4. Webhook Secret Authentication

​Response Processing

​Response Extraction

​Error Mapping

​Retry Configuration

​Security & Best Practices

​Credential Security

​API Key Prefixes

​Rate Limiting

​Example Configurations

​Weather API GET Request

​GitHub API GET user info Request

​Usage in Conversations

​Troubleshooting

​Common Issues

​Debug Information

​Cost & Limitations

​GCal — Check Availability

​Prerequisites

​Configuration

​What the caller hears

​Common configurations

​Inspection requests

​Vendor catch-up calls

​Sales colleague handovers

​Failure handling

​Cost & limitations

Quick Overview

End Call

Transition Message

Transfer Call

Transition Message

Display Agent Caller ID

Warm vs Cold Transfer

Transferrable Contacts

Custom Function Call

Key Features

Configuration Overview

Function Configuration

Function Name

Function Description

Parameter Specification

API Configuration

API Endpoint

HTTP Method

Timeout

Authentication Methods

1. API Key Authentication

2. Bearer Token Authentication

3. Basic Authentication

4. Webhook Secret Authentication

Response Processing

Response Extraction

Error Mapping

Retry Configuration

Security & Best Practices

Credential Security

API Key Prefixes

Rate Limiting

Example Configurations

Weather API GET Request

GitHub API GET user info Request

Usage in Conversations

Troubleshooting

Common Issues

Debug Information

Cost & Limitations

GCal — Check Availability

Prerequisites

Configuration

What the caller hears

Common configurations

Inspection requests

Vendor catch-up calls

Sales colleague handovers

Failure handling

Cost & limitations