Voicebot

Voicebot Configuration JSON Structure

Routing for your voicebot

To enable voicebot routing, you will need a phone number configured in your LeadDesk account. Once the voicebot configuration has been prepared, as described below, contact LeadDesk Support and request that the number be connected to the URL hosting your custom voicebot JSON configuration.

The JSON configuration defines the voicebot behaviour, including prompts, available tools, transfer logic, and platform functions such as call transfer or hangup handling.

JSON Structure

A voicebot configuration is a JSON object that defines how a voicebot behaves during a call, which voice it uses, how it detects speech, which backend endpoint receives function calls, and which platform tools the bot is allowed to use.

The configuration is made up of these top-level fields:

{
  "system": "...",
  "endpoint": "...",
  "httpMethod": "POST",
  "voice": "...",
  "silenceMs": "...",
  "detectionThreshold": "...",
  "tools": [],
  "initialGreeting": "..."
}

Top-Level Fields

Field	Type	Required	Description
`system`	string	Yes	The main instruction prompt that defines the bot’s role, behavior, language rules, escalation rules, and call-handling logic.
`endpoint`	string	Yes	The HTTP endpoint used for backend function calls.
`httpMethod`	string	Yes	The HTTP method used when sending requests to the endpoint. Usually POST.
`voice`	string	Yes	The voice used for generated speech.
`silenceMs`	string or number	Yes	The amount of caller silence, in milliseconds, before the bot treats the caller’s turn as complete.
`detectionThreshold`	string or number	Yes	The confidence threshold used for speech, turn, or intent detection.
`tools`	array	No	A list of callable functions available to the bot during the call.
`initialGreeting`	string	Yes	The message spoken at the beginning of the call.

system

The system field is a single string containing the main behavioral instructions for the bot.

It commonly includes:

Section	Purpose
Role	Defines who the bot is and what it is supposed to do.
Language rules	Defines which language the bot should use and how it should phrase responses.
Conversation style	Defines tone, length, formality, and response constraints.
Restrictions	Defines what the bot must not do.
Error handling	Defines how the bot should react to unclear, incomplete, or incorrectly transcribed input.
Escalation rules	Defines when the bot should transfer, collect details, or send information forward.
Call closing rules	Defines when the bot may end the call.

For example:

{
  "system": "# Role:\nYou are a voicebot for Example Company.\n\n# Language:\nAlways answer in English.\n\n# Behavior:\nKeep answers short and practical."
}

Because JSON strings cannot contain raw line breaks, line breaks are represented with \n.

endpoint

The endpoint field contains the backend URL used for function-call handling.

Example:

{
  "endpoint": "https://voicebot.example.com/api/function-call/+358401234567"
}

This endpoint is typically called when the bot invokes a platform function, such as transferring the call or sending a message.

httpMethod

The httpMethod field defines which HTTP method is used when calling the configured endpoint.

Example:

{
  "httpMethod": "POST"
}

Most voicebot function-call integrations use POST, because the bot sends structured data in the request body.

voice

The voice field selects the text-to-speech voice used by the bot. The available values depend on the voice platform.

Example:

{
  "voice": "alloy"
}

silenceMs

The silenceMs field controls how long the system waits during silence before deciding that the caller has finished speaking. A lower value makes the bot respond faster, but may interrupt callers more easily. A higher value gives callers more time to pause naturally.

Example:

{
  "silenceMs": "500"
}

detectionThreshold

The detectionThreshold field defines the confidence threshold used by the voicebot runtime. Higher values usually make detection stricter. Lower values may make the bot react more easily, but can increase false positives.

Example:

{
  "detectionThreshold": "0.95"
}

tools

The tools field is an array of function definitions. Each item describes one callable tool that the bot may use during the call.

See below for more about the tools array.

initialGreeting

The initialGreeting field defines what the bot says when the call starts. The value should usually match the start-of-call instruction in the system field.

Example:

{
  "initialGreeting": "Hello, this is Example Company. How can I help?"
}

Exploring the tools array

Here is the general structure of the tools array:

{
  "functionDescription": "...",
  "functionName": "...",
  "functionParameters": {
    "type": "object",
    "properties": {},
    "required": [],
    "additionalProperties": false
  }
}

In which:

Field	Type	Required	Description
`functionDescription`	string	Yes	Human-readable description of what the function does.
`functionName`	string	Yes	Name used when the bot calls the function.
`functionParameters`	object	Yes	JSON schema describing which parameters the function accepts.

functionParameters

The functionParameters object follows a JSON-schema-like structure.

Example:

{
  "functionParameters": {
    "type": "object",
    "properties": {
      "transferDestination": {
        "type": "string",
        "description": "The transfer destination."
      }
    },
    "required": ["transferDestination"],
    "additionalProperties": false
  }
}

Field	Purpose
type	Defines the expected JSON type. For tools, this is usually object
properties	Defines the accepted parameters.
required	Lists parameters that must be included when calling the function.
additional properties	Controls whether extra undeclared parameters are allowed.

Using “additionalProperties”: false is recommended because it prevents the bot from sending unexpected fields.

Example tool: Send Email

{
  "functionDescription": "Sends an email with the specified subject and body.",
  "functionName": "SendEmail",
  "functionParameters": {
    "type": "object",
    "properties": {
      "subject": {
        "type": "string",
        "description": "The subject line of the email."
      },
      "body": {
        "type": "string",
        "description": "The body content of the email."
      }
    },
    "required": ["subject", "body"],
    "additionalProperties": false
  }
}

Example function call:

{
  "subject": "Callback request from mock caller",
  "body": "Caller name: Alex Taylor\nCompany: Mockup Software Oy\nPhone: +358401234567\nRequest: Wants a callback about a stuck sales deal."
}

Platform functions

The voicebot supports two built-in functions that can be defined in the JSON. If these are defined in the configuration they will allow the voicebot to transfer or hangup the call.

platformHangup

{
  "functionDescription": "Ends the current call.",
  "functionName": "PlatformHangup",
  "functionParameters": {
    "type": "object",
    "properties": {},
    "required": [],
    "additionalProperties": false
  }
}

This tool does not require parameters.

platformTransfer

{
  "functionDescription": "Transfers the call to the specified destination.",
  "functionName": "PlatformTransfer",
  "functionParameters": {
    "type": "object",
    "properties": {
      "transferDestination": {
        "type": "string",
        "description": "The destination phone number, queue, or agent identifier."
      }
    },
    "required": ["transferDestination"],
    "additionalProperties": false
  }
}

Example function call:

{
  "transferDestination": "+358401234567"
}

Mock Runtime Example

Caller asks:

Can someone call me back about pricing

The bot collects the required details and then calls:

{
  "subject": "Callback request about pricing",
  "body": "Caller name: Alex Taylor\nCompany: Mockup Software Oy\nPhone: +358401234567\nRequest: Caller wants a callback about pricing."
}

Caller asks:

Can you transfer me to support?

The bot calls:

{
  "transferDestination": "+358401234567"
}

The caller says:

Thanks, goodbye.

Using PlatformHangup, the bot may call:

{}

Validation Checklist

Before deploying a voicebot configuration, check that:

Check	Expected result
JSON is valid	No trailing commas or unescaped line breaks
system is present	Bot has clear behavior instructions
endpoint is present	Function calls have a backend destination
httpMethod is valid	Usually POST
voice is supported	Voice exists in the runtime
silenceMs is reasonable	Usually a few hundred milliseconds
detectionThreshold is reasonable	Usually between 0 and 1.
Tool names are correct	Runtime recognizes each functionName
Tool schemas are strict	additionalProperties is usually false
Required parameters are correct	Required array matches actual function needs
Initial greeting is set	Bot knows what to say at call start