Voice AI Config Update

This article shows how to configure your Voice AI setup using tools. You’ll define your fulfilment prompt and connect it to different tools such as knowledge base lookups, transfers, hang-ups, bookings, and more.

Example Prompt

Here’s a full example of a Voice AI fulfilment prompt using tools:

You are a helpful voice assistant customer support agent named Navi. You work for Talkative Health.
Make sure that all output can be easily read out using a text to speech layer so don't use abbreviated formats for dates and times. When gathering information, ask for one piece of information at a time.

# Appointments
You can offer transferring them to a human, which involves a wait time our using the voice assistant service. If they choose to use the voice assistant, you will find available slots and then book a preferred slot. When offering slots don't offer more than 3 options. Before booking the appointment make sure you check the details.

# Parking
Customers can request on-site parking. You must check that the car has a valid MOT Status before allowing it.

# Emergency
If a customer is frustrated, say you will transfer them immediately.

@@@@@@@@@@
{
  "voice_ai_config": {
    "allow_interrupts": true
  }
}

Important notes:

• The prompt defines tone, process, and logic. Don’t include data collection logic here—use tools for that.

• Tool definitions are configured in the Tools section.

• The @@@@@@@@@@ line separates fulfilment logic from config overrides.

• JSON settings like allow_interrupts belong after the divider.

General Config

The first section of the JSON you can override any of the settings that are currently in the database or missing from the current database, in this case allow_interrupts. Any properties in here are optional. If allow_interrupts is missed VAI will default to false (no interrupts).

{
  "voice_ai_config": {
    "allow_interrupts": true
  }
}

Tools

Each tool has a label, prompt, and optional parameters or configuration. Prompts should be clear and short—just enough to tell the AI when and how to use the tool.

General information

All tools have the following required properties.

1. Label - Primarily an UI element and currently not utilised or read by the LLM
2. Prompt - Here you can explain to the LLM what the tool is, what it does and/or when to use it.
3. Parameters - The pieces of data that the tool requires in order to execute.
   • Type - the parameter type. Options are string, number, boolean,  null/empty, object, array 
   • Name - a ‘camelCase’ or ‘snake_case’ variable name. This will then be used as a reference for templating or is prescribed by custom tools.
   • Description Prompt - A clear explanation of the parameter's purpose and expected format. You can include examples of the expected formats.
4. Configuration - Bespoke to each individual tool.

Templating

Some properties will allow templating to insert configuration options, variables or call details into strings. For example, if you get the LLM to gather a parameter called songTitle you can add it into a URL for the HTTP_REQUEST tool using an template that might look like this: http://spotify.com/{{songTitle}}/artist. 

Transfer tool

Use this tool to transfer the caller to another agent or department.

Prompt

Use this tool to transfer the user to another agent or department.

Each destination requires:

• Type: Choose from Dial, SIP Refer, Mitel Refer

• Destination: e.164 phone number (e.g., +441234567890), SIP URI, or extension

• Description Prompt: A label like Billing Department

Knowledge Base Tool

Use this tool to fetch relevant information from a knowledge base.

Prompt

Use this tool to get additional context.

Parameters

• Type: This tells the system what kind of data to expect. In this case, it’s string, which just means a line of text.

• Name: This is the internal name used to refer to this input. searchText is a label the system uses—it’s not visible to users. Think of it as the “variable name” for the text the AI will search with.

• Description Prompt: This is where you describe what the AI should provide here. In this example:
  “Text to search the knowledge base for embeddings.”
  That means the AI will pass in relevant phrases or sentences from the conversation to find matching results in your KB.

Configuration

• Knowledge Base: Select from the dropdown - it should have access to all of your KBs.

• Context Size Limit: Typically set to 3500. Set the maximum character limit (1000-8000) for contextual information provided to the AI for each search term. Larger contexts may improve AI understanding but can slow down response times.

Hang Up Tool

This tool is used to tell the AI when to hang up the call without transfer.

Label

This is the display name for the tool so you can identify it easily in the tools list. In this case, it’s set as:

Hang Up Tool

Prompt

This tells the AI under what condition to use the tool. In this example:

"Use this tool to hang up the call when the user asks about refunds."

The AI will end the call automatically if the user requests a refund—no further interaction required.

HTTP Request Tool

This tool allows the AI to fetch live data from external APIs—for example, to check MOT status, retrieve booking availability, or validate information from another system.

Label

This is the display name used to help identify the tool. In this case:

HTTP Request Tool

Prompt

A brief instruction telling the AI when to use the tool.

Example

Use this tool to retrieve external information from a third-party API.

Configuration

• Method

  Choose the HTTP method the API expects. Common options include:

  • GET – for retrieving data

  • POST – for sending data

  • PUT / DELETE – for updates or deletions (less common in voice AI)

• URL
  The full URL of the API endpoint, including https://. You can use variables like {{parameterName}} to insert dynamic values.
  Example:
  https://api.example.com/vehicle/{{registrationNumber}}

• Headers

  Add headers like Authorization, Content-Type, or any other required by the API.

• Parameters (optional)

  Use this if the API requires extra values in the URL, body, or query string.

• Timeout (seconds)

  Optional - sets how long the system should wait before giving up on the request.

Placeholder Tool

This tool is used to capture and return structured values from user input—ideal for things like names, email addresses, or selected options.

Label

This is the display name for the tool that helps identify it in your list of tools. In this case:

Placeholder Tool

Prompt

This tells the AI when to use the tool. In this example you want to retrieve caller's name.

Example

Use this tool to return structured values from user input.

Parameters

• Type: string

  This defines the kind of input the AI should collect. A string is used for short text inputs like names or short answers.

• Name: fullName

  This is the internal identifier for the value being captured. It must be in lowercase letters with no spaces.

• Description Prompt:

  The caller's name, spoken clearly as part of the introduction.

  This tells the AI what kind of value it should provide for this parameter.

• Allowed Values (optional):

  Leave this empty when capturing free-form input like a name. You can use this field to restrict inputs to fixed options if needed (e.g., service type choices).

Configuration – Response

This determines what the AI should return once the value has been captured. You can use templating to format the response.

In the example the response's outputs will be customer's full name in a structured format that other systems can use.

Cal.com Slots Tool

Label

This is the display name used to identify the tool in your configuration. In this case:

Cal.com Slots Tool

Prompt

This instructs the AI on when to use the tool.In this example it is to use this tool to check available appointment slots.

Parameters

• Type: string

  This specifies the data format. A string is used for providing a formatted date.

• Name: startDate

  This is the internal reference name for the date value passed to the API.

• Description Prompt:

  Start date in YYYY-MM-DD format

  This tells the AI to use a correctly formatted date when calling the tool - e.g. 2025-06-11.

Configuration

• Cal.com API Token

  The token used to authenticate with your Cal.com account. You can generate it from the Cal.com API Keys page.

• Event Type ID

  This identifies which kind of appointment to fetch. You can find the ID in the URL when viewing your Cal.com event type (e.g. if the URL is .../event-types/2086911, use 2086911).

• Time Zone

  Defines the timezone used to interpret and return available times. Example: Europe/London

Cal.com Booking Tool

This tool is used to confirm and book an appointment slot via Cal.com after the user selects a time. It requires key details such as the appointment time, the caller’s name, and an email address for confirmation. SMS confirmations can also be configured.

Label

This is the name that helps identify the tool in your tools list. In this case:

Cal.com Booking Tool

Prompt

This tells the AI when to use the tool. In this example it is to use this tool to confirm and book a meeting using the selected slot.

Parameters

• Type: string

  The data type used for each input value.

• Name: start

  This is the internal name used to capture the start time of the appointment.

• Description Prompt:

  The start time of the chosen slot

  This tells the AI to pass in the selected appointment time in a proper timestamp format.

• Name: fullName

  Used to capture the caller’s full name.

• Description Prompt:

  User's full name

  Instructs the AI to gather the user’s name for the booking form.

You can add additional parameters if needed, such as email address, company name, or reason for booking.

Configuration

• Cal.com API Token

  This authenticates your system with Cal.com. You can generate a token via the Cal.com API Keys page.

• Event Type ID

  The unique ID for your Cal.com event type. You’ll find this in the URL when viewing a booking type (e.g., /event-types/2086911, use 2086911). Can be found in the URL after clicking an existing event type on the Event Types Page.

• Time Zone

  This sets the timezone used for interpreting and displaying booking times.

  Example: Europe/London

• Email

  The email to be used for the booking confirmation. This can be hardcoded or passed dynamically as a parameter.

SMS Confirmation

Optional—used to send an SMS to the user after booking.

• Phone Number

  A fallback phone number for confirmation if no number is gathered or known.

• SMS Template

  Defines the structure of the confirmation message.

  Example:

  {{meetTitle}} scheduled for {{meetDateTime}}. Join at {{meetUrl}}

• SMS Date Time Format

  Adjust how the date/time appears in the SMS. The default option works in most cases.