Create Tool

Authorizations

Authorization

string

header

required

Retrieve your API Key from Dashboard.

Body

application/json

ApiRequestTool
DtmfTool
EndCallTool
FunctionTool
GhlTool
MakeTool
TransferCallTool
OutputTool
BashTool
ComputerTool
TextEditorTool
QueryTool
GoogleCalendarCreateEventTool
GoogleSheetsRowAppendTool
GoogleCalendarCheckAvailabilityTool
SlackSendMessageTool
SmsSendTool
McpTool
GoHighLevelCalendarAvailabilityTool
GoHighLevelCalendarEventCreateTool
GoHighLevelContactCreateTool
GoHighLevelContactGetTool

type

enum<string>

required

The type of tool. "apiRequest" for API request tool.

Available options:

apiRequest

method

enum<string>

required

Available options:

POST,

GET

url

string

required

This is where the request will be sent.

messages

(ToolMessageStart · object | ToolMessageComplete · object | ToolMessageFailed · object | ToolMessageDelayed · object)[]

These are the messages that will be spoken to the user as the tool is running.

For some tools, this is auto-filled based on special fields like tool.destinations. For others like the function tool, these can be custom configured.

ToolMessageStart
ToolMessageComplete
ToolMessageFailed
ToolMessageDelayed

Show child attributes

messages.type

enum<string>

required

This message is triggered when the tool call starts.

This message is never triggered for async tools.

If this message is not provided, one of the default filler messages "Hold on a sec", "One moment", "Just a sec", "Give me a moment" or "This'll just take a sec" will be used.

Available options:

request-start

messages.contents

Text · object[]

This is an alternative to the content property. It allows to specify variants of the same content, one per language.

Usage:

If your assistants are multilingual, you can provide content for each language.
If you don't provide content for a language, the first item in the array will be automatically translated to the active language at that moment.

This will override the content property.

Show child attributes

messages.contents.type

enum<string>

required

Available options:

text

messages.contents.text

string

required

messages.contents.language

enum<string>

required

Available options:

aa,

ab,

ae,

af,

ak,

am,

an,

ar,

as,

av,

ay,

az,

ba,

be,

bg,

bh,

bi,

bm,

bn,

bo,

br,

bs,

ca,

ce,

ch,

co,

cr,

cs,

cu,

cv,

cy,

da,

de,

dv,

dz,

ee,

el,

en,

eo,

es,

et,

eu,

fa,

ff,

fi,

fj,

fo,

fr,

fy,

ga,

gd,

gl,

gn,

gu,

gv,

ha,

he,

hi,

ho,

hr,

ht,

hu,

hy,

hz,

ia,

id,

ie,

ig,

ii,

ik,

io,

is,

it,

iu,

ja,

jv,

ka,

kg,

ki,

kj,

kk,

kl,

km,

kn,

ko,

kr,

ks,

ku,

kv,

kw,

ky,

la,

lb,

lg,

li,

ln,

lo,

lt,

lu,

lv,

mg,

mh,

mi,

mk,

ml,

mn,

mr,

ms,

mt,

my,

na,

nb,

nd,

ne,

ng,

nl,

nn,

no,

nr,

nv,

ny,

oc,

oj,

om,

or,

os,

pa,

pi,

pl,

ps,

pt,

qu,

rm,

rn,

ro,

ru,

rw,

sa,

sc,

sd,

se,

sg,

si,

sk,

sl,

sm,

sn,

so,

sq,

sr,

ss,

st,

su,

sv,

sw,

ta,

te,

tg,

th,

ti,

tk,

tl,

tn,

to,

tr,

ts,

tt,

tw,

ty,

ug,

uk,

ur,

uz,

ve,

vi,

vo,

wa,

wo,

xh,

yi,

yue,

yo,

za,

zh,

zu

messages.blocking

boolean

default:false

This is an optional boolean that if true, the tool call will only trigger after the message is spoken. Default is false.

@default false

Example:

false

messages.content

string

This is the content that the assistant says when this message is triggered.

Maximum string length: 1000

messages.conditions

object[]

This is an optional array of conditions that the tool call arguments must meet in order for this message to be triggered.

Show child attributes

messages.conditions.operator

enum<string>

required

This is the operator you want to use to compare the parameter and value.

Available options:

eq,

neq,

gt,

gte,

lt,

lte

messages.conditions.param

string

required

This is the name of the parameter that you want to check.

Maximum string length: 1000

messages.conditions.value

string

required

This is the value you want to compare against the parameter.

Maximum string length: 1000

timeoutSeconds

number

This is the timeout in seconds for the request. Defaults to 20 seconds.

@default 20

Required range: 1 <= x <= 300

Example:

20

name

string

This is the name of the tool. This will be passed to the model.

Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 40.

Maximum string length: 40

description

string

This is the description of the tool. This will be passed to the model.

Maximum string length: 1000

body

object

This is the body of the request.

Show child attributes

body.type

enum<string>

required

This is the type of output you'd like.

string, number, integer, boolean are the primitive types and should be obvious.

array and object are more interesting and quite powerful. They allow you to define nested structures.

For array, you can define the schema of the items in the array using the items property.

For object, you can define the properties of the object using the properties property.

Available options:

string,

number,

integer,

boolean,

array,

object

body.items

object

This is required if the type is "array". This is the schema of the items in the array.

This is of type JsonSchema. However, Swagger doesn't support circular references.

body.properties

object

This is required if the type is "object". This specifies the properties of the object.

This is a map of string to JsonSchema. However, Swagger doesn't support circular references.

body.description

string

This is the description to help the model understand what it needs to output.

body.pattern

string

This is the pattern of the string. This is a regex that will be used to validate the data in question. To use a common format, use the format property instead.

OpenAI documentation: https://platform.openai.com/docs/guides/structured-outputs#supported-properties

body.format

enum<string>

This is the format of the string. To pass a regex, use the pattern property instead.

OpenAI documentation: https://platform.openai.com/docs/guides/structured-outputs?api-mode=chat&type-restrictions=string-restrictions

Available options:

date-time,

time,

date,

duration,

email,

hostname,

ipv4,

ipv6,

uuid

body.required

string[]

This is a list of properties that are required.

This only makes sense if the type is "object".

body.enum

string[]

This array specifies the allowed values that can be used to restrict the output of the model.

body.title

string

This is the title of the schema.

headers

object

These are the headers to send in the request.

Show child attributes

headers.type

enum<string>

required

This is the type of output you'd like.

string, number, integer, boolean are the primitive types and should be obvious.

array and object are more interesting and quite powerful. They allow you to define nested structures.

For array, you can define the schema of the items in the array using the items property.

For object, you can define the properties of the object using the properties property.

Available options:

string,

number,

integer,

boolean,

array,

object

headers.items

object

This is required if the type is "array". This is the schema of the items in the array.

This is of type JsonSchema. However, Swagger doesn't support circular references.

headers.properties

object

This is required if the type is "object". This specifies the properties of the object.

This is a map of string to JsonSchema. However, Swagger doesn't support circular references.

headers.description

string

This is the description to help the model understand what it needs to output.

headers.pattern

string

This is the pattern of the string. This is a regex that will be used to validate the data in question. To use a common format, use the format property instead.

OpenAI documentation: https://platform.openai.com/docs/guides/structured-outputs#supported-properties

headers.format

enum<string>

This is the format of the string. To pass a regex, use the pattern property instead.

OpenAI documentation: https://platform.openai.com/docs/guides/structured-outputs?api-mode=chat&type-restrictions=string-restrictions

Available options:

date-time,

time,

date,

duration,

email,

hostname,

ipv4,

ipv6,

uuid

headers.required

string[]

This is a list of properties that are required.

This only makes sense if the type is "object".

headers.enum

string[]

This array specifies the allowed values that can be used to restrict the output of the model.

headers.title

string

This is the title of the schema.

backoffPlan

object

This is the backoff plan if the request fails. Defaults to undefined (the request will not be retried).

@default undefined (the request will not be retried)

Show child attributes

backoffPlan.type

object

required

This is the type of backoff plan to use. Defaults to fixed.

@default fixed

Example:

"fixed"

backoffPlan.maxRetries

number

required

This is the maximum number of retries to attempt if the request fails. Defaults to 0 (no retries).

@default 0

Required range: 0 <= x <= 10

Example:

0

backoffPlan.baseDelaySeconds

number

required

This is the base delay in seconds. For linear backoff, this is the delay between each retry. For exponential backoff, this is the initial delay.

Required range: 0 <= x <= 10

Example:

1

variableExtractionPlan

object

This is the plan to extract variables from the tool's response. These will be accessible during the call and stored in call.artifact.variableValues after the call.

Usage:

Use aliases to extract variables from the tool's response body. (Most common case)

{
  "aliases": [
    {
      "key": "customerName",
      "value": "{{customer.name}}"
    },
    {
      "key": "customerAge",
      "value": "{{customer.age}}"
    }
  ]
}

The tool response body is made available to the liquid template.

Use aliases to extract variables from the tool's response body if the response is an array.

{
  "aliases": [
    {
      "key": "customerName",
      "value": "{{$[0].name}}"
    },
    {
      "key": "customerAge",
      "value": "{{$[0].age}}"
    }
  ]
}

$ is a shorthand for the tool's response body. $[0] is the first item in the array. $[n] is the nth item in the array. Note, $ is available regardless of the response body type (both object and array).

Use aliases to extract variables from the tool's response headers.

{
  "aliases": [
    {
      "key": "customerName",
      "value": "{{tool.response.headers.customer-name}}"
    },
    {
      "key": "customerAge",
      "value": "{{tool.response.headers.customer-age}}"
    }
  ]
}

tool.response is made available to the liquid template. Particularly, both tool.response.headers and tool.response.body are available. Note, tool.response is available regardless of the response body type (both object and array).

Use schema to extract a large portion of the tool's response body.

4.1. If you hit example.com and it returns {"name": "John", "age": 30}, then you can specify the schema as:

{
  "schema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      },
      "age": {
        "type": "number"
      }
    }
  }
}

4.2. If you hit example.com and it returns {"name": {"first": "John", "last": "Doe"}}, then you can specify the schema as:

{
  "schema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "object",
        "properties": {
          "first": {
            "type": "string"
          },
          "last": {
            "type": "string"
          }
        }
      }
    }
  }
}

These will be extracted as {{ name }} and {{ age }} respectively. To emphasize, object properties are extracted as direct global variables.

4.3. If you hit example.com and it returns {"name": {"first": "John", "last": "Doe"}}, then you can specify the schema as:

{
  "schema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "object",
        "properties": {
          "first": {
            "type": "string"
          },
          "last": {
            "type": "string"
          }
        }
      }
    }
  }
}

These will be extracted as {{ name }}. And, {{ name.first }} and {{ name.last }} will be accessible.

4.4. If you hit example.com and it returns ["94123", "94124"], then you can specify the schema as:

{
  "schema": {
    "type": "array",
    "title": "zipCodes",
    "items": {
      "type": "string"
    }
  }
}

This will be extracted as {{ zipCodes }}. To access the array items, you can use {{ zipCodes[0] }} and {{ zipCodes[1] }}.

4.5. If you hit example.com and it returns [{"name": "John", "age": 30, "zipCodes": ["94123", "94124"]}, {"name": "Jane", "age": 25, "zipCodes": ["94125", "94126"]}], then you can specify the schema as:

{
  "schema": {
    "type": "array",
    "title": "people",
    "items": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "age": {
          "type": "number"
        },
        "zipCodes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    }
  }
}

This will be extracted as {{ people }}. To access the array items, you can use {{ people[n].name }}, {{ people[n].age }}, {{ people[n].zipCodes }}, {{ people[n].zipCodes[0] }} and {{ people[n].zipCodes[1] }}.

Note: Both aliases and schema can be used together.

Show child attributes

variableExtractionPlan.schema

object

This is the schema to extract.

Examples:

To extract object properties, you can use the following schema:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "number"
    }
  }
}

These will be extracted as {{ name }} and {{ age }} respectively. To emphasize, object properties are extracted as direct global variables.

To extract nested properties, you can use the following schema:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "object",
      "properties": {
        "first": {
          "type": "string"
        },
        "last": {
          "type": "string"
        }
      }
    }
  }
}

These will be extracted as {{ name }}. And, {{ name.first }} and {{ name.last }} will be accessible.

To extract array items, you can use the following schema:

{
  "type": "array",
  "title": "zipCodes",
  "items": {
    "type": "string"
  }
}

This will be extracted as {{ zipCodes }}. To access the array items, you can use {{ zipCodes[0] }} and {{ zipCodes[1] }}.

To extract array of objects, you can use the following schema:

{
  "type": "array",
  "name": "people",
  "items": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      },
      "age": {
        "type": "number"
      },
      "zipCodes": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  }
}

Show child attributes

variableExtractionPlan.schema.type

enum<string>

required

This is the type of output you'd like.

string, number, integer, boolean are the primitive types and should be obvious.

array and object are more interesting and quite powerful. They allow you to define nested structures.

For array, you can define the schema of the items in the array using the items property.

For object, you can define the properties of the object using the properties property.

Available options:

string,

number,

integer,

boolean,

array,

object

variableExtractionPlan.schema.items

object

This is required if the type is "array". This is the schema of the items in the array.

This is of type JsonSchema. However, Swagger doesn't support circular references.

variableExtractionPlan.schema.properties

object

This is required if the type is "object". This specifies the properties of the object.

This is a map of string to JsonSchema. However, Swagger doesn't support circular references.

variableExtractionPlan.schema.description

string

This is the description to help the model understand what it needs to output.

variableExtractionPlan.schema.pattern

string

This is the pattern of the string. This is a regex that will be used to validate the data in question. To use a common format, use the format property instead.

OpenAI documentation: https://platform.openai.com/docs/guides/structured-outputs#supported-properties

variableExtractionPlan.schema.format

enum<string>

This is the format of the string. To pass a regex, use the pattern property instead.

OpenAI documentation: https://platform.openai.com/docs/guides/structured-outputs?api-mode=chat&type-restrictions=string-restrictions

Available options:

date-time,

time,

date,

duration,

email,

hostname,

ipv4,

ipv6,

uuid

variableExtractionPlan.schema.required

string[]

This is a list of properties that are required.

This only makes sense if the type is "object".

variableExtractionPlan.schema.enum

string[]

This array specifies the allowed values that can be used to restrict the output of the model.

variableExtractionPlan.schema.title

string

This is the title of the schema.

variableExtractionPlan.aliases

object[]

These are additional variables to create.

These will be accessible during the call as {{key}} and stored in call.artifact.variableValues after the call.

Example:

{
  "aliases": [
    {
      "key": "customerName",
      "value": "{{name}}"
    },
    {
      "key": "fullName",
      "value": "{{firstName}} {{lastName}}"
    },
    {
      "key": "greeting",
      "value": "Hello {{name}}, welcome to {{company}}!"
    },
    {
      "key": "customerEmail",
      "value": "{{addresses[0].city}}"
    },
    {
      "key": "something",
      "value": "{{any liquid}}"
    }
  ]
}

This will create variables customerName, fullName, customerEmail, greeting, and something. To access these variables, you can reference them as {{customerName}}, {{fullName}}, {{customerEmail}}, {{greeting}}, and {{something}}.

Show child attributes

variableExtractionPlan.aliases.key

string

required

This is the key of the variable.

This variable will be accessible during the call as {{key}} and stored in call.artifact.variableValues after the call.

Rules:

Must start with a letter (a-z, A-Z).
Subsequent characters can be letters, numbers, or underscores.
Minimum length of 1 and maximum length of 40.

Required string length: 1 - 40

variableExtractionPlan.aliases.value

string

required

This is the value of the variable.

This can reference existing variables, use filters, and perform transformations.

Examples: "{{name}}", "{{customer.email}}", "Hello {{name | upcase}}"

Maximum string length: 10000

function

object

This is the function definition of the tool.

For endCall, transferCall, and dtmf tools, this is auto-filled based on tool-specific fields like tool.destinations. But, even in those cases, you can provide a custom function definition for advanced use cases.

An example of an advanced use case is if you want to customize the message that's spoken for endCall tool. You can specify a function where it returns an argument "reason". Then, in messages array, you can have many "request-complete" messages. One of these messages will be triggered if the messages[].conditions matches the "reason" argument.

Show child attributes

function.name

string

required

This is the the name of the function to be called.

Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.

Maximum string length: 64

function.strict

boolean

default:false

This is a boolean that controls whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the parameters field. Only a subset of JSON Schema is supported when strict is true. Learn more about Structured Outputs in the OpenAI guide.

@default false

function.description

string

This is the description of what the function does, used by the AI to choose when and how to call the function.

Maximum string length: 1000

function.parameters

object

These are the parameters the functions accepts, described as a JSON Schema object.

See the OpenAI guide for examples, and the JSON Schema reference for documentation about the format.

Omitting parameters defines a function with an empty parameter list.

Show child attributes

function.parameters.type

enum<string>

required

This must be set to 'object'. It instructs the model to return a JSON object containing the function call properties.

Available options:

object

function.parameters.properties

object

required

This provides a description of the properties required by the function. JSON Schema can be used to specify expectations for each property. Refer to this doc for a comprehensive guide on JSON Schema.

Show child attributes

function.parameters.properties.{key}

object

Show child attributes

function.parameters.properties.{key}.type

enum<string>

required

This is the type of output you'd like.

string, number, integer, boolean are the primitive types and should be obvious.

array and object are more interesting and quite powerful. They allow you to define nested structures.

For array, you can define the schema of the items in the array using the items property.

For object, you can define the properties of the object using the properties property.

Available options:

string,

number,

integer,

boolean,

array,

object

function.parameters.properties.{key}.items

object

This is required if the type is "array". This is the schema of the items in the array.

This is of type JsonSchema. However, Swagger doesn't support circular references.

function.parameters.properties.{key}.properties

object

This is required if the type is "object". This specifies the properties of the object.

This is a map of string to JsonSchema. However, Swagger doesn't support circular references.

function.parameters.properties.{key}.description

string

This is the description to help the model understand what it needs to output.

function.parameters.properties.{key}.pattern

string

This is the pattern of the string. This is a regex that will be used to validate the data in question. To use a common format, use the format property instead.

OpenAI documentation: https://platform.openai.com/docs/guides/structured-outputs#supported-properties

function.parameters.properties.{key}.format

enum<string>

This is the format of the string. To pass a regex, use the pattern property instead.

OpenAI documentation: https://platform.openai.com/docs/guides/structured-outputs?api-mode=chat&type-restrictions=string-restrictions

Available options:

date-time,

time,

date,

duration,

email,

hostname,

ipv4,

ipv6,

uuid

function.parameters.properties.{key}.required

string[]

This is a list of properties that are required.

This only makes sense if the type is "object".

function.parameters.properties.{key}.enum

string[]

This array specifies the allowed values that can be used to restrict the output of the model.

function.parameters.properties.{key}.title

string

This is the title of the schema.

function.parameters.required

string[]

This specifies the properties that are required by the function.

Response

201 - application/json

ApiRequestTool
DtmfTool
EndCallTool
FunctionTool
GhlTool
MakeTool
TransferCallTool
OutputTool
BashTool
ComputerTool
TextEditorTool
QueryTool
GoogleCalendarCreateEventTool
GoogleSheetsRowAppendTool
GoogleCalendarCheckAvailabilityTool
SlackSendMessageTool
SmsSendTool
McpTool
GoHighLevelCalendarAvailabilityTool
GoHighLevelCalendarEventCreateTool
GoHighLevelContactCreateTool
GoHighLevelContactGetTool

type

enum<string>

required

The type of tool. "apiRequest" for API request tool.

Available options:

apiRequest

method

enum<string>

required

Available options:

POST,

GET

string

required

This is the unique identifier for the tool.

orgId

string

required

This is the unique identifier for the organization that this tool belongs to.

createdAt

string<date-time>

required

This is the ISO 8601 date-time string of when the tool was created.

updatedAt

string<date-time>

required

This is the ISO 8601 date-time string of when the tool was last updated.

url

string

required

This is where the request will be sent.

messages

(ToolMessageStart · object | ToolMessageComplete · object | ToolMessageFailed · object | ToolMessageDelayed · object)[]

These are the messages that will be spoken to the user as the tool is running.

For some tools, this is auto-filled based on special fields like tool.destinations. For others like the function tool, these can be custom configured.

ToolMessageStart
ToolMessageComplete
ToolMessageFailed
ToolMessageDelayed

Show child attributes

messages.type

enum<string>

required

This message is triggered when the tool call starts.

This message is never triggered for async tools.

If this message is not provided, one of the default filler messages "Hold on a sec", "One moment", "Just a sec", "Give me a moment" or "This'll just take a sec" will be used.

Available options:

request-start

messages.contents

Text · object[]

This is an alternative to the content property. It allows to specify variants of the same content, one per language.

Usage:

If your assistants are multilingual, you can provide content for each language.
If you don't provide content for a language, the first item in the array will be automatically translated to the active language at that moment.

This will override the content property.

Show child attributes

messages.contents.type

enum<string>

required

Available options:

text

messages.contents.text

string

required

messages.contents.language

enum<string>

required

Available options:

aa,

ab,

ae,

af,

ak,

am,

an,

ar,

as,

av,

ay,

az,

ba,

be,

bg,

bh,

bi,

bm,

bn,

bo,

br,

bs,

ca,

ce,

ch,

co,

cr,

cs,

cu,

cv,

cy,

da,

de,

dv,

dz,

ee,

el,

en,

eo,

es,

et,

eu,

fa,

ff,

fi,

fj,

fo,

fr,

fy,

ga,

gd,

gl,

gn,

gu,

gv,

ha,

he,

hi,

ho,

hr,

ht,

hu,

hy,

hz,

ia,

id,

ie,

ig,

ii,

ik,

io,

is,

it,

iu,

ja,

jv,

ka,

kg,

ki,

kj,

kk,

kl,

km,

kn,

ko,

kr,

ks,

ku,

kv,

kw,

ky,

la,

lb,

lg,

li,

ln,

lo,

lt,

lu,

lv,

mg,

mh,

mi,

mk,

ml,

mn,

mr,

ms,

mt,

my,

na,

nb,

nd,

ne,

ng,

nl,

nn,

no,

nr,

nv,

ny,

oc,

oj,

om,

or,

os,

pa,

pi,

pl,

ps,

pt,

qu,

rm,

rn,

ro,

ru,

rw,

sa,

sc,

sd,

se,

sg,

si,

sk,

sl,

sm,

sn,

so,

sq,

sr,

ss,

st,

su,

sv,

sw,

ta,

te,

tg,

th,

ti,

tk,

tl,

tn,

to,

tr,

ts,

tt,

tw,

ty,

ug,

uk,

ur,

uz,

ve,

vi,

vo,

wa,

wo,

xh,

yi,

yue,

yo,

za,

zh,

zu

messages.blocking

boolean

default:false

This is an optional boolean that if true, the tool call will only trigger after the message is spoken. Default is false.

@default false

Example:

false

messages.content

string

This is the content that the assistant says when this message is triggered.

Maximum string length: 1000

messages.conditions

object[]

This is an optional array of conditions that the tool call arguments must meet in order for this message to be triggered.

Show child attributes

messages.conditions.operator

enum<string>

required

This is the operator you want to use to compare the parameter and value.

Available options:

eq,

neq,

gt,

gte,

lt,

lte

messages.conditions.param

string

required

This is the name of the parameter that you want to check.

Maximum string length: 1000

messages.conditions.value

string

required

This is the value you want to compare against the parameter.

Maximum string length: 1000

timeoutSeconds

number

This is the timeout in seconds for the request. Defaults to 20 seconds.

@default 20

Required range: 1 <= x <= 300

Example:

20

function

object

This is the function definition of the tool.

Show child attributes

function.name

string

required

This is the the name of the function to be called.

Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.

Maximum string length: 64

function.strict

boolean

default:false

@default false

function.description

string

This is the description of what the function does, used by the AI to choose when and how to call the function.

Maximum string length: 1000

function.parameters

object

These are the parameters the functions accepts, described as a JSON Schema object.

See the OpenAI guide for examples, and the JSON Schema reference for documentation about the format.

Omitting parameters defines a function with an empty parameter list.

Show child attributes

function.parameters.type

enum<string>

required

This must be set to 'object'. It instructs the model to return a JSON object containing the function call properties.

Available options:

object

function.parameters.properties

object

required

This provides a description of the properties required by the function. JSON Schema can be used to specify expectations for each property. Refer to this doc for a comprehensive guide on JSON Schema.

Show child attributes

function.parameters.properties.{key}

object

Show child attributes

function.parameters.properties.{key}.type

enum<string>

required

This is the type of output you'd like.

string, number, integer, boolean are the primitive types and should be obvious.

array and object are more interesting and quite powerful. They allow you to define nested structures.

For array, you can define the schema of the items in the array using the items property.

For object, you can define the properties of the object using the properties property.

Available options:

string,

number,

integer,

boolean,

array,

object

function.parameters.properties.{key}.items

object

This is required if the type is "array". This is the schema of the items in the array.

This is of type JsonSchema. However, Swagger doesn't support circular references.

function.parameters.properties.{key}.properties

object

This is required if the type is "object". This specifies the properties of the object.

This is a map of string to JsonSchema. However, Swagger doesn't support circular references.

function.parameters.properties.{key}.description

string

This is the description to help the model understand what it needs to output.

function.parameters.properties.{key}.pattern

string

This is the pattern of the string. This is a regex that will be used to validate the data in question. To use a common format, use the format property instead.

OpenAI documentation: https://platform.openai.com/docs/guides/structured-outputs#supported-properties

function.parameters.properties.{key}.format

enum<string>

This is the format of the string. To pass a regex, use the pattern property instead.

OpenAI documentation: https://platform.openai.com/docs/guides/structured-outputs?api-mode=chat&type-restrictions=string-restrictions

Available options:

date-time,

time,

date,

duration,

email,

hostname,

ipv4,

ipv6,

uuid

function.parameters.properties.{key}.required

string[]

This is a list of properties that are required.

This only makes sense if the type is "object".

function.parameters.properties.{key}.enum

string[]

This array specifies the allowed values that can be used to restrict the output of the model.

function.parameters.properties.{key}.title

string

This is the title of the schema.

function.parameters.required

string[]

This specifies the properties that are required by the function.

name

string

This is the name of the tool. This will be passed to the model.

Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 40.

Maximum string length: 40

description

string

This is the description of the tool. This will be passed to the model.

Maximum string length: 1000

body

object

This is the body of the request.

Show child attributes

body.type

enum<string>

required

This is the type of output you'd like.

string, number, integer, boolean are the primitive types and should be obvious.

array and object are more interesting and quite powerful. They allow you to define nested structures.

For array, you can define the schema of the items in the array using the items property.

For object, you can define the properties of the object using the properties property.

Available options:

string,

number,

integer,

boolean,

array,

object

body.items

object

This is required if the type is "array". This is the schema of the items in the array.

This is of type JsonSchema. However, Swagger doesn't support circular references.

body.properties

object

This is required if the type is "object". This specifies the properties of the object.

This is a map of string to JsonSchema. However, Swagger doesn't support circular references.

body.description

string

This is the description to help the model understand what it needs to output.

body.pattern

string

This is the pattern of the string. This is a regex that will be used to validate the data in question. To use a common format, use the format property instead.

OpenAI documentation: https://platform.openai.com/docs/guides/structured-outputs#supported-properties

body.format

enum<string>

This is the format of the string. To pass a regex, use the pattern property instead.

OpenAI documentation: https://platform.openai.com/docs/guides/structured-outputs?api-mode=chat&type-restrictions=string-restrictions

Available options:

date-time,

time,

date,

duration,

email,

hostname,

ipv4,

ipv6,

uuid

body.required

string[]

This is a list of properties that are required.

This only makes sense if the type is "object".

body.enum

string[]

This array specifies the allowed values that can be used to restrict the output of the model.

body.title

string

This is the title of the schema.

headers

object

These are the headers to send in the request.

Show child attributes

headers.type

enum<string>

required

This is the type of output you'd like.

string, number, integer, boolean are the primitive types and should be obvious.

array and object are more interesting and quite powerful. They allow you to define nested structures.

For array, you can define the schema of the items in the array using the items property.

For object, you can define the properties of the object using the properties property.

Available options:

string,

number,

integer,

boolean,

array,

object

headers.items

object

This is required if the type is "array". This is the schema of the items in the array.

This is of type JsonSchema. However, Swagger doesn't support circular references.

headers.properties

object

This is required if the type is "object". This specifies the properties of the object.

This is a map of string to JsonSchema. However, Swagger doesn't support circular references.

headers.description

string

This is the description to help the model understand what it needs to output.

headers.pattern

string

This is the pattern of the string. This is a regex that will be used to validate the data in question. To use a common format, use the format property instead.

OpenAI documentation: https://platform.openai.com/docs/guides/structured-outputs#supported-properties

headers.format

enum<string>

This is the format of the string. To pass a regex, use the pattern property instead.

OpenAI documentation: https://platform.openai.com/docs/guides/structured-outputs?api-mode=chat&type-restrictions=string-restrictions

Available options:

date-time,

time,

date,

duration,

email,

hostname,

ipv4,

ipv6,

uuid

headers.required

string[]

This is a list of properties that are required.

This only makes sense if the type is "object".

headers.enum

string[]

This array specifies the allowed values that can be used to restrict the output of the model.

headers.title

string

This is the title of the schema.

backoffPlan

object

This is the backoff plan if the request fails. Defaults to undefined (the request will not be retried).

@default undefined (the request will not be retried)

Show child attributes

backoffPlan.type

object

required

This is the type of backoff plan to use. Defaults to fixed.

@default fixed

Example:

"fixed"

backoffPlan.maxRetries

number

required

This is the maximum number of retries to attempt if the request fails. Defaults to 0 (no retries).

@default 0

Required range: 0 <= x <= 10

Example:

0

backoffPlan.baseDelaySeconds

number

required

This is the base delay in seconds. For linear backoff, this is the delay between each retry. For exponential backoff, this is the initial delay.

Required range: 0 <= x <= 10

Example:

1

variableExtractionPlan

object

This is the plan to extract variables from the tool's response. These will be accessible during the call and stored in call.artifact.variableValues after the call.

Usage:

Use aliases to extract variables from the tool's response body. (Most common case)

{
  "aliases": [
    {
      "key": "customerName",
      "value": "{{customer.name}}"
    },
    {
      "key": "customerAge",
      "value": "{{customer.age}}"
    }
  ]
}

The tool response body is made available to the liquid template.

Use aliases to extract variables from the tool's response body if the response is an array.

{
  "aliases": [
    {
      "key": "customerName",
      "value": "{{$[0].name}}"
    },
    {
      "key": "customerAge",
      "value": "{{$[0].age}}"
    }
  ]
}

Use aliases to extract variables from the tool's response headers.

{
  "aliases": [
    {
      "key": "customerName",
      "value": "{{tool.response.headers.customer-name}}"
    },
    {
      "key": "customerAge",
      "value": "{{tool.response.headers.customer-age}}"
    }
  ]
}

Use schema to extract a large portion of the tool's response body.

4.1. If you hit example.com and it returns {"name": "John", "age": 30}, then you can specify the schema as:

{
  "schema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      },
      "age": {
        "type": "number"
      }
    }
  }
}

4.2. If you hit example.com and it returns {"name": {"first": "John", "last": "Doe"}}, then you can specify the schema as:

{
  "schema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "object",
        "properties": {
          "first": {
            "type": "string"
          },
          "last": {
            "type": "string"
          }
        }
      }
    }
  }
}

These will be extracted as {{ name }} and {{ age }} respectively. To emphasize, object properties are extracted as direct global variables.

4.3. If you hit example.com and it returns {"name": {"first": "John", "last": "Doe"}}, then you can specify the schema as:

{
  "schema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "object",
        "properties": {
          "first": {
            "type": "string"
          },
          "last": {
            "type": "string"
          }
        }
      }
    }
  }
}

These will be extracted as {{ name }}. And, {{ name.first }} and {{ name.last }} will be accessible.

4.4. If you hit example.com and it returns ["94123", "94124"], then you can specify the schema as:

{
  "schema": {
    "type": "array",
    "title": "zipCodes",
    "items": {
      "type": "string"
    }
  }
}

This will be extracted as {{ zipCodes }}. To access the array items, you can use {{ zipCodes[0] }} and {{ zipCodes[1] }}.

{
  "schema": {
    "type": "array",
    "title": "people",
    "items": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "age": {
          "type": "number"
        },
        "zipCodes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    }
  }
}

Note: Both aliases and schema can be used together.

Show child attributes

variableExtractionPlan.schema

object

This is the schema to extract.

Examples:

To extract object properties, you can use the following schema:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "number"
    }
  }
}

These will be extracted as {{ name }} and {{ age }} respectively. To emphasize, object properties are extracted as direct global variables.

To extract nested properties, you can use the following schema:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "object",
      "properties": {
        "first": {
          "type": "string"
        },
        "last": {
          "type": "string"
        }
      }
    }
  }
}

These will be extracted as {{ name }}. And, {{ name.first }} and {{ name.last }} will be accessible.

To extract array items, you can use the following schema:

{
  "type": "array",
  "title": "zipCodes",
  "items": {
    "type": "string"
  }
}

This will be extracted as {{ zipCodes }}. To access the array items, you can use {{ zipCodes[0] }} and {{ zipCodes[1] }}.

To extract array of objects, you can use the following schema:

{
  "type": "array",
  "name": "people",
  "items": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      },
      "age": {
        "type": "number"
      },
      "zipCodes": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  }
}

Show child attributes

variableExtractionPlan.schema.type

enum<string>

required

This is the type of output you'd like.

string, number, integer, boolean are the primitive types and should be obvious.

array and object are more interesting and quite powerful. They allow you to define nested structures.

For array, you can define the schema of the items in the array using the items property.

For object, you can define the properties of the object using the properties property.

Available options:

string,

number,

integer,

boolean,

array,

object

variableExtractionPlan.schema.items

object

This is required if the type is "array". This is the schema of the items in the array.

This is of type JsonSchema. However, Swagger doesn't support circular references.

variableExtractionPlan.schema.properties

object

This is required if the type is "object". This specifies the properties of the object.

This is a map of string to JsonSchema. However, Swagger doesn't support circular references.

variableExtractionPlan.schema.description

string

This is the description to help the model understand what it needs to output.

variableExtractionPlan.schema.pattern

string

This is the pattern of the string. This is a regex that will be used to validate the data in question. To use a common format, use the format property instead.

OpenAI documentation: https://platform.openai.com/docs/guides/structured-outputs#supported-properties

variableExtractionPlan.schema.format

enum<string>

This is the format of the string. To pass a regex, use the pattern property instead.

OpenAI documentation: https://platform.openai.com/docs/guides/structured-outputs?api-mode=chat&type-restrictions=string-restrictions

Available options:

date-time,

time,

date,

duration,

email,

hostname,

ipv4,

ipv6,

uuid

variableExtractionPlan.schema.required

string[]

This is a list of properties that are required.

This only makes sense if the type is "object".

variableExtractionPlan.schema.enum

string[]

This array specifies the allowed values that can be used to restrict the output of the model.

variableExtractionPlan.schema.title

string

This is the title of the schema.

variableExtractionPlan.aliases

object[]

These are additional variables to create.

These will be accessible during the call as {{key}} and stored in call.artifact.variableValues after the call.

Example:

{
  "aliases": [
    {
      "key": "customerName",
      "value": "{{name}}"
    },
    {
      "key": "fullName",
      "value": "{{firstName}} {{lastName}}"
    },
    {
      "key": "greeting",
      "value": "Hello {{name}}, welcome to {{company}}!"
    },
    {
      "key": "customerEmail",
      "value": "{{addresses[0].city}}"
    },
    {
      "key": "something",
      "value": "{{any liquid}}"
    }
  ]
}

Show child attributes

variableExtractionPlan.aliases.key

string

required

This is the key of the variable.

This variable will be accessible during the call as {{key}} and stored in call.artifact.variableValues after the call.

Rules:

Must start with a letter (a-z, A-Z).
Subsequent characters can be letters, numbers, or underscores.
Minimum length of 1 and maximum length of 40.

Required string length: 1 - 40

variableExtractionPlan.aliases.value

string

required

This is the value of the variable.

This can reference existing variables, use filters, and perform transformations.

Examples: "{{name}}", "{{customer.email}}", "Hello {{name | upcase}}"

Maximum string length: 10000

API Documentation

Webhooks

Voice Agent UI

STT Usage

Endpoint Examples

Assistants

Calls

Campaigns

Chats

Files

Knowledge Base

Logs

Phone Numbers

Sessions

Tools

Workflow

SDK

Outbound

Concurrency

Authorizations

Body

Response