List Assistants

Authorizations

Authorization

string

header

required

Retrieve your API Key from Dashboard.

Query Parameters

limit

number

This is the maximum number of items to return. Defaults to 100.

Required range: 0 <= x <= 1000

createdAtGt

string<date-time>

This will return items where the createdAt is greater than the specified value.

createdAtLt

string<date-time>

This will return items where the createdAt is less than the specified value.

createdAtGe

string<date-time>

This will return items where the createdAt is greater than or equal to the specified value.

createdAtLe

string<date-time>

This will return items where the createdAt is less than or equal to the specified value.

updatedAtGt

string<date-time>

This will return items where the updatedAt is greater than the specified value.

updatedAtLt

string<date-time>

This will return items where the updatedAt is less than the specified value.

updatedAtGe

string<date-time>

This will return items where the updatedAt is greater than or equal to the specified value.

updatedAtLe

string<date-time>

This will return items where the updatedAt is less than or equal to the specified value.

Response

200 - application/json

string

required

This is the unique identifier for the assistant.

orgId

string

required

This is the unique identifier for the org that this assistant belongs to.

createdAt

string<date-time>

required

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

updatedAt

string<date-time>

required

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

transcriber

AssemblyAITranscriber · object

These are the options for the assistant's transcriber.

AssemblyAITranscriber
AzureSpeechTranscriber
CustomTranscriber
DeepgramTranscriber
ElevenLabsTranscriber
GladiaTranscriber
GoogleTranscriber
SpeechmaticsTranscriber
TalkscriberTranscriber
OpenAITranscriber
CartesiaTranscriber

Show child attributes

transcriber.provider

enum<string>

required

This is the transcription provider that will be used.

Available options:

assembly-ai

transcriber.language

enum<string>

This is the language that will be set for the transcription.

Available options:

en

transcriber.confidenceThreshold

number

Transcripts below this confidence threshold will be discarded.

@default 0.4

Required range: 0 <= x <= 1

Example:

0.4

transcriber.enableUniversalStreamingApi

boolean

Uses Assembly AI's new Universal Streaming API. See: https://www.assemblyai.com/docs/speech-to-text/universal-streaming

@default false

Example:

false

transcriber.formatTurns

boolean

This enables formatting of transcripts. Only used when enableUniversalStreamingApi is true.

@default false

Example:

false

transcriber.endOfTurnConfidenceThreshold

number

The confidence threshold to use when determining if the end of a turn has been reached. Only used when enableUniversalStreamingApi is true.

@default 0.7

Required range: 0 <= x <= 1

Example:

0.7

transcriber.minEndOfTurnSilenceWhenConfident

number

The minimum amount of silence in milliseconds required to detect end of turn when confident. Only used when enableUniversalStreamingApi is true.

@default 160

Required range: x >= 0

Example:

160

transcriber.wordFinalizationMaxWaitTime

number

The maximum wait time for word finalization. Only used when enableUniversalStreamingApi is true.

@default 160

Required range: x >= 0

Example:

160

transcriber.maxTurnSilence

number

The maximum amount of silence in milliseconds allowed in a turn before end of turn is triggered. Only used when enableUniversalStreamingApi is true.

@default 400

Required range: x >= 0

Example:

400

transcriber.realtimeUrl

string

The WebSocket URL that the transcriber connects to.

transcriber.wordBoost

string[]

Add up to 2500 characters of custom vocabulary.

Maximum string length: 2500

transcriber.endUtteranceSilenceThreshold

number

The duration of the end utterance silence threshold in milliseconds.

transcriber.disablePartialTranscripts

boolean

Disable partial transcripts. Set to true to not receive partial transcripts. Defaults to false.

transcriber.fallbackPlan

object

This is the plan for voice provider fallbacks in the event that the primary voice provider fails.

Show child attributes

transcriber.fallbackPlan.transcribers

required

AssemblyAI
Azure
Custom
Deepgram
ElevenLabs
Gladia
Google
Talkscriber
Speechmatics
OpenAI
Cartesia

Show child attributes

transcriber.fallbackPlan.transcribers.provider

enum<string>

required

This is the transcription provider that will be used.

Available options:

assembly-ai

transcriber.fallbackPlan.transcribers.language

enum<string>

This is the language that will be set for the transcription.

Available options:

en

transcriber.fallbackPlan.transcribers.confidenceThreshold

number

Transcripts below this confidence threshold will be discarded.

@default 0.4

Required range: 0 <= x <= 1

Example:

0.4

transcriber.fallbackPlan.transcribers.enableUniversalStreamingApi

boolean

Uses Assembly AI's new Universal Streaming API. See: https://www.assemblyai.com/docs/speech-to-text/universal-streaming

@default false

Example:

false

transcriber.fallbackPlan.transcribers.formatTurns

boolean

This enables formatting of transcripts. Only used when enableUniversalStreamingApi is true.

@default false

Example:

false

transcriber.fallbackPlan.transcribers.endOfTurnConfidenceThreshold

number

The confidence threshold to use when determining if the end of a turn has been reached. Only used when enableUniversalStreamingApi is true.

@default 0.7

Required range: 0 <= x <= 1

Example:

0.7

transcriber.fallbackPlan.transcribers.minEndOfTurnSilenceWhenConfident

number

The minimum amount of silence in milliseconds required to detect end of turn when confident. Only used when enableUniversalStreamingApi is true.

@default 160

Required range: x >= 0

Example:

160

transcriber.fallbackPlan.transcribers.wordFinalizationMaxWaitTime

number

The maximum wait time for word finalization. Only used when enableUniversalStreamingApi is true.

@default 160

Required range: x >= 0

Example:

160

transcriber.fallbackPlan.transcribers.maxTurnSilence

number

The maximum amount of silence in milliseconds allowed in a turn before end of turn is triggered. Only used when enableUniversalStreamingApi is true.

@default 400

Required range: x >= 0

Example:

400

transcriber.fallbackPlan.transcribers.realtimeUrl

string

The WebSocket URL that the transcriber connects to.

transcriber.fallbackPlan.transcribers.wordBoost

string[]

Add up to 2500 characters of custom vocabulary.

Maximum string length: 2500

transcriber.fallbackPlan.transcribers.endUtteranceSilenceThreshold

number

The duration of the end utterance silence threshold in milliseconds.

transcriber.fallbackPlan.transcribers.disablePartialTranscripts

boolean

Disable partial transcripts. Set to true to not receive partial transcripts. Defaults to false.

model

Anthropic · object

These are the options for the assistant's LLM.

Anthropic
Anyscale
Cerebras
CustomLLM
DeepInfra
DeepSeek
Google
Groq
InflectionAI
OpenAI
OpenRouter
PerplexityAI
Together
XAI

Show child attributes

model.model

enum<string>

required

The specific Anthropic/Claude model that will be used.

Available options:

claude-3-opus-20240229,

claude-3-sonnet-20240229,

claude-3-haiku-20240307,

claude-3-5-sonnet-20240620,

claude-3-5-sonnet-20241022,

claude-3-5-haiku-20241022,

claude-3-7-sonnet-20250219,

claude-opus-4-20250514,

claude-sonnet-4-20250514

model.provider

enum<string>

required

The provider identifier for Anthropic.

Available options:

anthropic

model.messages

object[]

This is the starting state for the conversation.

Show child attributes

model.messages.content

string | null

required

Maximum string length: 100000000

model.messages.role

enum<string>

required

Available options:

assistant,

function,

user,

system,

tool

model.tools

These are the tools that the assistant can use during the call. To use existing tools, use toolIds.

Both tools and toolIds can be used together.

ApiRequestTool
BashTool
ComputerTool
DtmfTool
EndCallTool
FunctionTool
GoHighLevelCalendarAvailabilityTool
GoHighLevelCalendarEventCreateTool
GoHighLevelContactCreateTool
GoHighLevelContactGetTool
GoogleCalendarCheckAvailabilityTool
GoogleCalendarCreateEventTool
GoogleSheetsRowAppendTool
McpTool
QueryTool
SlackSendMessageTool
SmsTool
TextEditorTool
TransferCallTool

Show child attributes

model.tools.type

enum<string>

required

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

Available options:

apiRequest

model.tools.method

enum<string>

required

Available options:

POST,

GET

model.tools.url

string

required

This is where the request will be sent.

model.tools.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

model.tools.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

model.tools.messages.contents

any[]

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.

model.tools.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

model.tools.messages.content

string

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

Maximum string length: 1000

model.tools.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

model.tools.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

model.tools.messages.conditions.param

string

required

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

Maximum string length: 1000

model.tools.messages.conditions.value

string

required

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

Maximum string length: 1000

model.tools.timeoutSeconds

number

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

@default 20

Required range: 1 <= x <= 300

Example:

20

model.tools.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

model.tools.description

string

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

Maximum string length: 1000

model.tools.body

object

This is the body of the request.

Show child attributes

model.tools.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

model.tools.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.

model.tools.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.

model.tools.body.description

string

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

model.tools.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

model.tools.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

model.tools.body.required

string[]

This is a list of properties that are required.

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

model.tools.body.enum

string[]

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

model.tools.body.title

string

This is the title of the schema.

model.tools.headers

object

These are the headers to send in the request.

Show child attributes

model.tools.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

model.tools.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.

model.tools.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.

model.tools.headers.description

string

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

model.tools.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

model.tools.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

model.tools.headers.required

string[]

This is a list of properties that are required.

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

model.tools.headers.enum

string[]

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

model.tools.headers.title

string

This is the title of the schema.

model.tools.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

model.tools.backoffPlan.type

object

required

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

@default fixed

Example:

"fixed"

model.tools.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

model.tools.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

model.tools.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

model.tools.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

model.tools.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

model.tools.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.

model.tools.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.

model.tools.variableExtractionPlan.schema.description

string

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

model.tools.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

model.tools.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

model.tools.variableExtractionPlan.schema.required

string[]

This is a list of properties that are required.

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

model.tools.variableExtractionPlan.schema.enum

string[]

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

model.tools.variableExtractionPlan.schema.title

string

This is the title of the schema.

model.tools.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

model.tools.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

model.tools.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

model.tools.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

model.tools.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

model.tools.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

model.tools.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

model.tools.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

model.tools.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

model.tools.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

model.tools.function.parameters.properties.{key}

object

Show child attributes

model.tools.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

model.tools.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.

model.tools.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.

model.tools.function.parameters.properties.{key}.description

string

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

model.tools.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

model.tools.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

model.tools.function.parameters.properties.{key}.required

string[]

This is a list of properties that are required.

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

model.tools.function.parameters.properties.{key}.enum

string[]

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

model.tools.function.parameters.properties.{key}.title

string

This is the title of the schema.

model.tools.function.parameters.required

string[]

This specifies the properties that are required by the function.

model.toolIds

string[]

These are the tools that the assistant can use during the call. To use transient tools, use tools.

Both tools and toolIds can be used together.

model.knowledgeBase

Custom · object

These are the options for the knowledge base.

Show child attributes

model.knowledgeBase.provider

enum<string>

required

This knowledge base is bring your own knowledge base implementation.

Available options:

custom-knowledge-base

model.knowledgeBase.server

object

required

This is where the knowledge base request will be sent.

Request Example:

POST https://{server.url} Content-Type: application/json

{ "messsage": { "type": "knowledge-base-request", "messages": [ { "role": "user", "content": "Why is ocean blue?" } ], ...other metadata about the call... } }

Response Expected:

{
  "message": {
     "role": "assistant",
     "content": "The ocean is blue because water absorbs everything but blue.",
  }, // YOU CAN RETURN THE EXACT RESPONSE TO SPEAK
  "documents": [
    {
      "content": "The ocean is blue primarily because water absorbs colors in the red part of the light spectrum and scatters the blue light, making it more visible to our eyes.",
      "similarity": 1
    },
    {
      "content": "Blue light is scattered more by the water molecules than other colors, enhancing the blue appearance of the ocean.",
      "similarity": .5
    }
  ] // OR, YOU CAN RETURN AN ARRAY OF DOCUMENTS THAT WILL BE SENT TO THE MODEL
}

Show child attributes

model.knowledgeBase.server.timeoutSeconds

number

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

@default 20

Required range: 1 <= x <= 300

Example:

20

model.knowledgeBase.server.url

string

This is where the request will be sent.

model.knowledgeBase.server.headers

object

These are the headers to include in the request.

Each key-value pair represents a header name and its value.

model.knowledgeBase.server.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

model.knowledgeBase.server.backoffPlan.type

object

required

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

@default fixed

Example:

"fixed"

model.knowledgeBase.server.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

model.knowledgeBase.server.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

model.knowledgeBaseId

string

This is the ID of the knowledge base the model will use.

model.thinking

object

Optional configuration for Anthropic's thinking feature. Only applicable for claude-3-7-sonnet-20250219 model. If provided, maxTokens must be greater than thinking.budgetTokens.

Show child attributes

model.thinking.type

enum<string>

required

Available options:

enabled

model.thinking.budgetTokens

number

required

The maximum number of tokens to allocate for thinking. Must be between 1024 and 100000 tokens.

Required range: 1024 <= x <= 100000

model.temperature

number

This is the temperature that will be used for calls. Default is 0 to leverage caching for lower latency.

Required range: 0 <= x <= 2

model.maxTokens

number

This is the max number of tokens that the assistant will be allowed to generate in each turn of the conversation. Default is 250.

Required range: 50 <= x <= 10000

model.emotionRecognitionEnabled

boolean

This determines whether we detect user's emotion while they speak and send it as an additional info to model.

Default false because the model is usually are good at understanding the user's emotion from text.

@default false

model.numFastTurns

number

This sets how many turns at the start of the conversation to use a smaller, faster model from the same provider before switching to the primary model. Example, gpt-3.5-turbo if provider is openai.

Default is 0.

@default 0

Required range: x >= 0

voice

AzureVoice · object

These are the options for the assistant's voice.

AzureVoice
CartesiaVoice
CustomVoice
DeepgramVoice
ElevenLabsVoice
HumeVoice
LMNTVoice
NeuphonicVoice
OpenAIVoice
PlayHTVoice
RimeAIVoice
SmallestAIVoice
TavusVoice
cozmoxVoice
SesameVoice
InworldVoice

Show child attributes

voice.provider

enum<string>

required

This is the voice provider that will be used.

Available options:

azure

voice.voiceId

required

This is the provider-specific ID that will be used.

Available options:

andrew,

brian,

emma

voice.cachingEnabled

boolean

default:true

This is the flag to toggle voice caching for the assistant.

Example:

true

voice.chunkPlan

object

This is the plan for chunking the model output before it is sent to the voice provider.

Show child attributes

voice.chunkPlan.enabled

boolean

This determines whether the model output is chunked before being sent to the voice provider. Default true.

Usage:

To rely on the voice provider's audio generation logic, set this to false.
If seeing issues with quality, set this to true.

If disabled, cozmox-provided audio control tokens like will not work.

@default true

Example:

true

voice.chunkPlan.minCharacters

number

This is the minimum number of characters in a chunk.

Usage:

To increase quality, set this to a higher value.
To decrease latency, set this to a lower value.

@default 30

Required range: 1 <= x <= 80

Example:

30

voice.chunkPlan.punctuationBoundaries

enum<string>[]

These are the punctuations that are considered valid boundaries for a chunk to be created.

Usage:

To increase quality, constrain to fewer boundaries.
To decrease latency, enable all.

Default is automatically set to balance the trade-off between quality and latency based on the provider.

Available options:

。,

，,

.,

!,

?,

;,

),

،,

۔,

।,

॥,

|,

||,

,,

:

Example:

[
  "。",
  "，",
  ".",
  "!",
  "?",
  ";",
  "،",
  "۔",
  "।",
  "॥",
  "|",
  "||",
  ",",
  ":"
]

voice.chunkPlan.formatPlan

object

This is the plan for formatting the chunk before it is sent to the voice provider.

Show child attributes

voice.chunkPlan.formatPlan.enabled

boolean

This determines whether the chunk is formatted before being sent to the voice provider. This helps with enunciation. This includes phone numbers, emails and addresses. Default true.

Usage:

To rely on the voice provider's formatting logic, set this to false.

If voice.chunkPlan.enabled is false, this is automatically false since there's no chunk to format.

@default true

Example:

true

voice.chunkPlan.formatPlan.numberToDigitsCutoff

number

This is the cutoff after which a number is converted to individual digits instead of being spoken as words.

Example:

If cutoff 2025, "12345" is converted to "1 2 3 4 5" while "1200" is converted to "twelve hundred".

Usage:

If your use case doesn't involve IDs like zip codes, set this to a high value.
If your use case involves IDs that are shorter than 5 digits, set this to a lower value.

@default 2025

Required range: x >= 0

Example:

2025

voice.chunkPlan.formatPlan.replacements

(ExactReplacement · object | RegexReplacement · object)[]

These are the custom replacements you can make to the chunk before it is sent to the voice provider.

Usage:

To replace a specific word or phrase with a different word or phrase, use the ExactReplacement type. Eg. { type: 'exact', key: 'hello', value: 'hi' }
To replace a word or phrase that matches a pattern, use the RegexReplacement type. Eg. { type: 'regex', regex: '\\b[a-zA-Z]{5}\\b', value: 'hi' }

@default []

ExactReplacement
RegexReplacement

Show child attributes

voice.chunkPlan.formatPlan.replacements.type

enum<string>

required

This is the exact replacement type. You can use this to replace a specific word or phrase with a different word or phrase.

Usage:

Replace "hello" with "hi": { type: 'exact', key: 'hello', value: 'hi' }
Replace "good morning" with "good day": { type: 'exact', key: 'good morning', value: 'good day' }
Replace a specific name: { type: 'exact', key: 'John Doe', value: 'Jane Smith' }
Replace an acronym: { type: 'exact', key: 'AI', value: 'Artificial Intelligence' }
Replace a company name with its phonetic pronunciation: { type: 'exact', key: 'cozmox', value: 'Vappy' }

Available options:

exact

voice.chunkPlan.formatPlan.replacements.key

string

required

This is the key to replace.

voice.chunkPlan.formatPlan.replacements.value

string

required

This is the value that will replace the match.

Maximum string length: 1000

voice.chunkPlan.formatPlan.replacements.replaceAllEnabled

boolean

default:false

This option let's you control whether to replace all instances of the key or only the first one. By default, it only replaces the first instance. Examples:

For { type: 'exact', key: 'hello', value: 'hi', replaceAllEnabled: false }. Before: "hello world, hello universe" | After: "hi world, hello universe"
For { type: 'exact', key: 'hello', value: 'hi', replaceAllEnabled: true }. Before: "hello world, hello universe" | After: "hi world, hi universe" @default false

voice.chunkPlan.formatPlan.formattersEnabled

enum<string>[]

List of formatters to apply. If not provided, all default formatters will be applied. If provided, only the specified formatters will be applied. Note: Some essential formatters like angle bracket removal will always be applied. @default undefined

Available options:

markdown,

asterisk,

quote,

dash,

newline,

colon,

acronym,

dollarAmount,

email,

date,

time,

distance,

unit,

percentage,

phoneNumber,

number,

stripAsterisk

voice.speed

number

This is the speed multiplier that will be used.

Required range: 0.5 <= x <= 2

voice.fallbackPlan

object

This is the plan for voice provider fallbacks in the event that the primary voice provider fails.

Show child attributes

voice.fallbackPlan.voices

required

This is the list of voices to fallback to in the event that the primary voice provider fails.

Azure
Cartesia
Hume
CustomVoice
Deepgram
ElevenLabs
cozmox
LMNT
OpenAI
PlayHT
RimeAI
Smallest AI
TavusVoice
Neuphonic
Sesame
Inworld

Show child attributes

voice.fallbackPlan.voices.provider

enum<string>

required

This is the voice provider that will be used.

Available options:

azure

voice.fallbackPlan.voices.voiceId

required

This is the provider-specific ID that will be used.

Available options:

andrew,

brian,

emma

voice.fallbackPlan.voices.cachingEnabled

boolean

default:true

This is the flag to toggle voice caching for the assistant.

Example:

true

voice.fallbackPlan.voices.speed

number

This is the speed multiplier that will be used.

Required range: 0.5 <= x <= 2

voice.fallbackPlan.voices.chunkPlan

object

This is the plan for chunking the model output before it is sent to the voice provider.

Show child attributes

voice.fallbackPlan.voices.chunkPlan.enabled

boolean

This determines whether the model output is chunked before being sent to the voice provider. Default true.

Usage:

To rely on the voice provider's audio generation logic, set this to false.
If seeing issues with quality, set this to true.

If disabled, cozmox-provided audio control tokens like will not work.

@default true

Example:

true

voice.fallbackPlan.voices.chunkPlan.minCharacters

number

This is the minimum number of characters in a chunk.

Usage:

To increase quality, set this to a higher value.
To decrease latency, set this to a lower value.

@default 30

Required range: 1 <= x <= 80

Example:

30

voice.fallbackPlan.voices.chunkPlan.punctuationBoundaries

enum<string>[]

These are the punctuations that are considered valid boundaries for a chunk to be created.

Usage:

To increase quality, constrain to fewer boundaries.
To decrease latency, enable all.

Default is automatically set to balance the trade-off between quality and latency based on the provider.

Available options:

。,

，,

.,

!,

?,

;,

),

،,

۔,

।,

॥,

|,

||,

,,

:

Example:

[
  "。",
  "，",
  ".",
  "!",
  "?",
  ";",
  "،",
  "۔",
  "।",
  "॥",
  "|",
  "||",
  ",",
  ":"
]

voice.fallbackPlan.voices.chunkPlan.formatPlan

object

This is the plan for formatting the chunk before it is sent to the voice provider.

Show child attributes

voice.fallbackPlan.voices.chunkPlan.formatPlan.enabled

boolean

This determines whether the chunk is formatted before being sent to the voice provider. This helps with enunciation. This includes phone numbers, emails and addresses. Default true.

Usage:

To rely on the voice provider's formatting logic, set this to false.

If voice.chunkPlan.enabled is false, this is automatically false since there's no chunk to format.

@default true

Example:

true

voice.fallbackPlan.voices.chunkPlan.formatPlan.numberToDigitsCutoff

number

This is the cutoff after which a number is converted to individual digits instead of being spoken as words.

Example:

If cutoff 2025, "12345" is converted to "1 2 3 4 5" while "1200" is converted to "twelve hundred".

Usage:

If your use case doesn't involve IDs like zip codes, set this to a high value.
If your use case involves IDs that are shorter than 5 digits, set this to a lower value.

@default 2025

Required range: x >= 0

Example:

2025

voice.fallbackPlan.voices.chunkPlan.formatPlan.replacements

(ExactReplacement · object | RegexReplacement · object)[]

These are the custom replacements you can make to the chunk before it is sent to the voice provider.

Usage:

To replace a specific word or phrase with a different word or phrase, use the ExactReplacement type. Eg. { type: 'exact', key: 'hello', value: 'hi' }
To replace a word or phrase that matches a pattern, use the RegexReplacement type. Eg. { type: 'regex', regex: '\\b[a-zA-Z]{5}\\b', value: 'hi' }

@default []

ExactReplacement
RegexReplacement

Show child attributes

voice.fallbackPlan.voices.chunkPlan.formatPlan.replacements.type

enum<string>

required

This is the exact replacement type. You can use this to replace a specific word or phrase with a different word or phrase.

Usage:

Replace "hello" with "hi": { type: 'exact', key: 'hello', value: 'hi' }
Replace "good morning" with "good day": { type: 'exact', key: 'good morning', value: 'good day' }
Replace a specific name: { type: 'exact', key: 'John Doe', value: 'Jane Smith' }
Replace an acronym: { type: 'exact', key: 'AI', value: 'Artificial Intelligence' }
Replace a company name with its phonetic pronunciation: { type: 'exact', key: 'cozmox', value: 'Vappy' }

Available options:

exact

voice.fallbackPlan.voices.chunkPlan.formatPlan.replacements.key

string

required

This is the key to replace.

voice.fallbackPlan.voices.chunkPlan.formatPlan.replacements.value

string

required

This is the value that will replace the match.

Maximum string length: 1000

voice.fallbackPlan.voices.chunkPlan.formatPlan.replacements.replaceAllEnabled

boolean

default:false

This option let's you control whether to replace all instances of the key or only the first one. By default, it only replaces the first instance. Examples:

For { type: 'exact', key: 'hello', value: 'hi', replaceAllEnabled: false }. Before: "hello world, hello universe" | After: "hi world, hello universe"
For { type: 'exact', key: 'hello', value: 'hi', replaceAllEnabled: true }. Before: "hello world, hello universe" | After: "hi world, hi universe" @default false

voice.fallbackPlan.voices.chunkPlan.formatPlan.formattersEnabled

enum<string>[]

Available options:

markdown,

asterisk,

quote,

dash,

newline,

colon,

acronym,

dollarAmount,

email,

date,

time,

distance,

unit,

percentage,

phoneNumber,

number,

stripAsterisk

firstMessage

string

This is the first message that the assistant will say. This can also be a URL to a containerized audio file (mp3, wav, etc.).

If unspecified, assistant will wait for user to speak and use the model to respond once they speak.

Example:

"Hello! How can I help you today?"

firstMessageInterruptionsEnabled

boolean

default:false

firstMessageMode

enum<string>

This is the mode for the first message. Default is 'assistant-speaks-first'.

Use:

'assistant-speaks-first' to have the assistant speak first.
'assistant-waits-for-user' to have the assistant wait for the user to speak first.
'assistant-speaks-first-with-model-generated-message' to have the assistant speak first with a message generated by the model based on the conversation state. (assistant.model.messages at call start, call.messages at squad transfer points).

@default 'assistant-speaks-first'

Available options:

assistant-speaks-first,

assistant-speaks-first-with-model-generated-message,

assistant-waits-for-user

Example:

"assistant-speaks-first"

voicemailDetection

Google · object

These are the settings to configure or disable voicemail detection. Alternatively, voicemail detection can be configured using the model.tools=[VoicemailTool]. This uses Twilio's built-in detection while the VoicemailTool relies on the model to detect if a voicemail was reached. You can use neither of them, one of them, or both of them. By default, Twilio built-in detection is enabled while VoicemailTool is not.

Google
OpenAI
Twilio
cozmox

Show child attributes

voicemailDetection.provider

enum<string>

required

This is the provider to use for voicemail detection.

Available options:

google

voicemailDetection.beepMaxAwaitSeconds

number

default:30

This is the maximum duration from the start of the call that we will wait for a voicemail beep, before speaking our message

If we detect a voicemail beep before this, we will speak the message at that point.
Setting too low a value means that the bot will start speaking its voicemail message too early. If it does so before the actual beep, it will get cut off. You should definitely tune this to your use case.

@default 30 @min 0 @max 60

Required range: 0 <= x <= 30

voicemailDetection.backoffPlan

object

This is the backoff plan for the voicemail detection.

Show child attributes

voicemailDetection.backoffPlan.startAtSeconds

number

default:5

This is the number of seconds to wait before starting the first retry attempt.

Required range: x >= 0

voicemailDetection.backoffPlan.frequencySeconds

number

default:5

This is the interval in seconds between retry attempts.

Required range: x >= 2.5

voicemailDetection.backoffPlan.maxRetries

number

default:6

This is the maximum number of retry attempts before giving up.

Required range: 1 <= x <= 10

clientMessages

enum<string>[]

These are the messages that will be sent to your Client SDKs. Default is conversation-update,function-call,hang,model-output,speech-update,status-update,transfer-update,transcript,tool-calls,user-interrupted,voice-input,workflow.node.started. You can check the shape of the messages in ClientMessage schema.

Available options:

conversation-update,

function-call,

function-call-result,

hang,

language-changed,

metadata,

model-output,

speech-update,

status-update,

transcript,

tool-calls,

tool-calls-result,

tool.completed,

transfer-update,

user-interrupted,

voice-input,

workflow.node.started

Example:

[
  "conversation-update",
  "function-call",
  "hang",
  "model-output",
  "speech-update",
  "status-update",
  "transfer-update",
  "transcript",
  "tool-calls",
  "user-interrupted",
  "voice-input",
  "workflow.node.started"
]

serverMessages

enum<string>[]

These are the messages that will be sent to your Server URL. Default is conversation-update,end-of-call-report,function-call,hang,speech-update,status-update,tool-calls,transfer-destination-request,user-interrupted. You can check the shape of the messages in ServerMessage schema.

Available options:

conversation-update,

end-of-call-report,

function-call,

hang,

language-changed,

language-change-detected,

model-output,

phone-call-control,

speech-update,

status-update,

transcript,

transcript[transcriptType="final"],

tool-calls,

transfer-destination-request,

transfer-update,

user-interrupted,

voice-input

Example:

[
  "conversation-update",
  "end-of-call-report",
  "function-call",
  "hang",
  "speech-update",
  "status-update",
  "tool-calls",
  "transfer-destination-request",
  "user-interrupted"
]

silenceTimeoutSeconds

number

How many seconds of silence to wait before ending the call. Defaults to 30.

@default 30

Required range: 10 <= x <= 3600

Example:

30

maxDurationSeconds

number

This is the maximum number of seconds that the call will last. When the call reaches this duration, it will be ended.

@default 600 (10 minutes)

Required range: 10 <= x <= 43200

Example:

600

backgroundSound

This is the background sound in the call. Default for phone calls is 'office' and default for web calls is 'off'. You can also provide a custom sound by providing a URL to an audio file.

Available options:

off,

office

Example:

"office"

backgroundDenoisingEnabled

boolean

deprecated

This enables filtering of noise and background speech while the user is talking.

Default false while in beta.

@default false

Example:

false

modelOutputInMessagesEnabled

boolean

This determines whether the model's output is used in conversation history rather than the transcription of assistant's speech.

Default false while in beta.

@default false

Example:

false

transportConfigurations

Twilio · object[]

These are the configurations to be passed to the transport providers of assistant's calls, like Twilio. You can store multiple configurations for different transport providers. For a call, only the configuration matching the call transport provider is used.

Show child attributes

transportConfigurations.provider

enum<string>

required

Available options:

twilio

transportConfigurations.timeout

number

The integer number of seconds that we should allow the phone to ring before assuming there is no answer. The default is 60 seconds and the maximum is 600 seconds. For some call flows, we will add a 5-second buffer to the timeout value you provide. For this reason, a timeout value of 10 seconds could result in an actual timeout closer to 15 seconds. You can set this to a short time, such as 15 seconds, to hang up before reaching an answering machine or voicemail.

@default 60

Required range: 1 <= x <= 600

Example:

60

transportConfigurations.record

boolean

Whether to record the call. Can be true to record the phone call, or false to not. The default is false.

@default false

Example:

false

transportConfigurations.recordingChannels

enum<string>

The number of channels in the final recording. Can be: mono or dual. The default is mono. mono records both legs of the call in a single channel of the recording file. dual records each leg to a separate channel of the recording file. The first channel of a dual-channel recording contains the parent call and the second channel contains the child call.

@default 'mono'

Available options:

mono,

dual

Example:

"mono"

observabilityPlan

Langfuse · object

This is the plan for observability of assistant's calls.

Currently, only Langfuse is supported.

Show child attributes

observabilityPlan.provider

enum<string>

required

Available options:

langfuse

observabilityPlan.tags

string[]

required

This is an array of tags to be added to the Langfuse trace. Tags allow you to categorize and filter traces. https://langfuse.com/docs/tracing-features/tags This is an array of tags to be added to the Langfuse trace. Tags allow you to categorize and filter traces. https://langfuse.com/docs/tracing-features/tags

observabilityPlan.metadata

object

This is a JSON object that will be added to the Langfuse trace. Traces can be enriched with metadata to better understand your users, application, and experiments. https://langfuse.com/docs/tracing-features/metadata By default it includes the call metadata, assistant metadata, and assistant overrides. This is a JSON object that will be added to the Langfuse trace. Traces can be enriched with metadata to better understand your users, application, and experiments. https://langfuse.com/docs/tracing-features/metadata By default it includes the call metadata, assistant metadata, and assistant overrides.

credentials

These are dynamic credentials that will be used for the assistant calls. By default, all the credentials are available for use in the call but you can supplement an additional credentials using this. Dynamic credentials override existing credentials.

AnthropicCredential
AnyscaleCredential
AssemblyAICredential
AzureCredential
AzureOpenAICredential
ByoSipTrunkCredential
CartesiaCredential
CerebrasCredential
CloudflareCredential
CustomLLMCredential
DeepgramCredential
DeepInfraCredential
DeepSeekCredential
ElevenLabsCredential
GcpCredential
GladiaCredential
GhlCredential
GoogleCredential
GroqCredential
HumeCredential
InflectionAICredential
LangfuseCredential
LmntCredential
MakeCredential
MistralCredential
NeuphonicCredential
OpenAICredential
OpenRouterCredential
PerplexityAICredential
PlayHTCredential
RimeAICredential
RunpodCredential
S3Credential
SmallestAICredential
SpeechmaticsCredential
SupabaseCredential
TavusCredential
TogetherAICredential
TrieveCredential
TwilioCredential
VonageCredential
WebhookCredential
XAiCredential
GoogleCalendarOAuth2ClientCredential
GoogleCalendarOAuth2AuthorizationCredential
GoogleSheetsOAuth2AuthorizationCredential
SlackOAuth2AuthorizationCredential
GoHighLevelMCPCredential

Show child attributes

credentials.provider

enum<string>

required

Available options:

anthropic

credentials.apiKey

string

required

This is not returned in the API.

Maximum string length: 10000

credentials.name

string

This is the name of credential. This is just for your reference.

Required string length: 1 - 40

hooks

(AssistantHookCallEnding · object | AssistantHookAssistantSpeechInterrupted · object | AssistantHookCustomerSpeechInterrupted · object)[]

This is a set of actions that will be performed on certain events.

AssistantHookCallEnding
AssistantHookAssistantSpeechInterrupted
AssistantHookCustomerSpeechInterrupted

Show child attributes

hooks.on

enum<string>

required

This is the event that triggers this hook

Available options:

call.ending

Maximum string length: 1000

hooks.do

(TransferAssistantHookAction · object | FunctionCallAssistantHookAction · object)[]

required

This is the set of actions to perform when the hook triggers

TransferAssistantHookAction
FunctionCallAssistantHookAction

Show child attributes

hooks.do.type

enum<string>

required

This is the type of action - must be "transfer"

Available options:

transfer

hooks.do.destination

NumberTransferDestination · object

This is the destination details for the transfer - can be a phone number or SIP URI

NumberTransferDestination
SipTransferDestination

Show child attributes

hooks.do.destination.type

enum<string>

required

Available options:

number

hooks.do.destination.number

string

required

This is the phone number to transfer the call to.

Required string length: 3 - 40

hooks.do.destination.message

This is spoken to the customer before connecting them to the destination.

Usage:

If this is not provided and transfer tool messages is not provided, default is "Transferring the call now".
If set to "", nothing is spoken. This is useful when you want to silently transfer. This is especially useful when transferring between assistants in a squad. In this scenario, you likely also want to set assistant.firstMessageMode=assistant-speaks-first-with-model-generated-message for the destination assistant.

This accepts a string or a ToolMessageStart class. Latter is useful if you want to specify multiple messages for different languages through the contents field.

hooks.do.destination.numberE164CheckEnabled

boolean

default:true

This is the flag to toggle the E164 check for the number field. This is an advanced property which should be used if you know your use case requires it.

Use cases:

false: To allow non-E164 numbers like +001234567890, 1234, or abc. This is useful for dialing out to non-E164 numbers on your SIP trunks.
true (default): To allow only E164 numbers like +14155551234. This is standard for PSTN calls.

If false, the number is still required to only contain alphanumeric characters (regex: /^\+?[a-zA-Z0-9]+$/).

@default true (E164 check is enabled)

hooks.do.destination.extension

string

This is the extension to dial after transferring the call to the number.

Required string length: 1 - 10

hooks.do.destination.callerId

string

This is the caller ID to use when transferring the call to the number.

Usage:

If not provided, the caller ID will be the number the call is coming from. Example, +14151111111 calls in to and the assistant transfers out to +16470000000. +16470000000 will see +14151111111 as the caller.
To change this behavior, provide a callerId.
Set to '{{customer.number}}' to always use the customer's number as the caller ID.
Set to '{{phoneNumber.number}}' to always use the phone number of the assistant as the caller ID.
Set to any E164 number to always use that number as the caller ID. This needs to be a number that is owned or verified by your Transport provider like Twilio.

For Twilio, you can read up more here: https://www.twilio.com/docs/voice/twiml/dial#callerid

Maximum string length: 40

hooks.do.destination.transferPlan

object

This configures how transfer is executed and the experience of the destination party receiving the call. Defaults to blind-transfer.

@default transferPlan.mode='blind-transfer'

Show child attributes

hooks.do.destination.transferPlan.mode

enum<string>

required

This configures how transfer is executed and the experience of the destination party receiving the call.

Usage:

blind-transfer: The assistant forwards the call to the destination without any message or summary.
blind-transfer-add-summary-to-sip-header: The assistant forwards the call to the destination and adds a SIP header X-Transfer-Summary to the call to include the summary.
warm-transfer-say-message: The assistant dials the destination, delivers the message to the destination party, connects the customer, and leaves the call.
warm-transfer-say-summary: The assistant dials the destination, provides a summary of the call to the destination party, connects the customer, and leaves the call.
warm-transfer-wait-for-operator-to-speak-first-and-then-say-message: The assistant dials the destination, waits for the operator to speak, delivers the message to the destination party, and then connects the customer.
warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary: The assistant dials the destination, waits for the operator to speak, provides a summary of the call to the destination party, and then connects the customer.
warm-transfer-twiml: The assistant dials the destination, executes the twiml instructions on the destination call leg, connects the customer, and leaves the call.
warm-transfer-experimental: The assistant puts the customer on hold, dials the destination, and if the destination answers (and is human), delivers a message or summary before connecting the customer. If the destination is unreachable or not human (e.g., with voicemail detection), the assistant delivers the fallbackMessage to the customer and optionally ends the call.

@default 'blind-transfer'

Available options:

blind-transfer,

blind-transfer-add-summary-to-sip-header,

warm-transfer-say-message,

warm-transfer-say-summary,

warm-transfer-twiml,

warm-transfer-wait-for-operator-to-speak-first-and-then-say-message,

warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary,

warm-transfer-experimental

hooks.do.destination.transferPlan.message

This is the message the assistant will deliver to the destination party before connecting the customer.

Usage:

Used only when mode is blind-transfer-add-summary-to-sip-header, warm-transfer-say-message, warm-transfer-wait-for-operator-to-speak-first-and-then-say-message, or warm-transfer-experimental.

hooks.do.destination.transferPlan.timeout

number

default:60

This is the timeout in seconds for the warm-transfer-wait-for-operator-to-speak-first-and-then-say-message/summary

@default 60

Required range: 1 <= x <= 600

hooks.do.destination.transferPlan.sipVerb

object

This specifies the SIP verb to use while transferring the call.

'refer': Uses SIP REFER to transfer the call (default)
'bye': Ends current call with SIP BYE
'dial': Uses SIP DIAL to transfer the call

hooks.do.destination.transferPlan.holdAudioUrl

string

This is the URL to an audio file played while the customer is on hold during transfer.

Usage:

Used only when mode is warm-transfer-experimental.
Used when transferring calls to play hold audio for the customer.
Must be a publicly accessible URL to an audio file.
Supported formats: MP3 and WAV.
If not provided, the default hold audio will be used.

hooks.do.destination.transferPlan.transferCompleteAudioUrl

string

This is the URL to an audio file played after the warm transfer message or summary is delivered to the destination party. It can be used to play a custom sound like 'beep' to notify that the transfer is complete.

Usage:

Used only when mode is warm-transfer-experimental.
Used when transferring calls to play hold audio for the destination party.
Must be a publicly accessible URL to an audio file.
Supported formats: MP3 and WAV.

hooks.do.destination.transferPlan.twiml

string

This is the TwiML instructions to execute on the destination call leg before connecting the customer.

Usage:

Used only when mode is warm-transfer-twiml.
Supports only Play, Say, Gather, Hangup and Pause verbs.
Maximum length is 4096 characters.

Example:

<Say voice="alice" language="en-US">Hello, transferring a customer to you.</Say>
<Pause length="2"/>
<Say>They called about billing questions.</Say>

Maximum string length: 4096

hooks.do.destination.transferPlan.summaryPlan

object

This is the plan for generating a summary of the call to present to the destination party.

Usage:

Used only when mode is blind-transfer-add-summary-to-sip-header or warm-transfer-say-summary or warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary or warm-transfer-experimental.

Show child attributes

hooks.do.destination.transferPlan.summaryPlan.messages

object[]

These are the messages used to generate the summary.

@default: [ { "role": "system", "content": "You are an expert note-taker. You will be given a transcript of a call. Summarize the call in 2-3 sentences. DO NOT return anything except the summary." }, { "role": "user", "content": "Here is the transcript:\n\n{{transcript}}\n\n. Here is the ended reason of the call:\n\n{{endedReason}}\n\n" } ]

You can customize by providing any messages you want.

Here are the template variables available:

{{transcript}}: The transcript of the call from call.artifact.transcript
{{systemPrompt}}: The system prompt of the call from assistant.model.messages[type=system].content
{{endedReason}}: The ended reason of the call from call.endedReason

hooks.do.destination.transferPlan.summaryPlan.enabled

boolean

This determines whether a summary is generated and stored in call.analysis.summary. Defaults to true.

Usage:

If you want to disable the summary, set this to false.

@default true

hooks.do.destination.transferPlan.summaryPlan.timeoutSeconds

number

This is how long the request is tried before giving up. When request times out, call.analysis.summary will be empty.

Usage:

To guarantee the summary is generated, set this value high. Note, this will delay the end of call report in cases where model is slow to respond.

@default 5 seconds

Required range: 1 <= x <= 60

hooks.do.destination.transferPlan.sipHeadersInReferToEnabled

boolean

This flag includes the sipHeaders from above in the refer to sip uri as url encoded query params.

@default false

hooks.do.destination.transferPlan.fallbackPlan

object

This configures the fallback plan when the transfer fails (destination unreachable, busy, or not human).

Usage:

Used only when mode is warm-transfer-experimental.
If not provided when using warm-transfer-experimental, a default message will be used.

Show child attributes

hooks.do.destination.transferPlan.fallbackPlan.message

required

This is the message the assistant will deliver to the customer if the transfer fails.

hooks.do.destination.transferPlan.fallbackPlan.endCallEnabled

boolean

default:true

This controls what happens after delivering the failure message to the customer.

true: End the call after delivering the failure message (default)
false: Keep the assistant on the call to continue handling the customer's request

@default true

hooks.do.destination.description

string

This is the description of the destination, used by the AI to choose when and how to transfer the call.

hooks.filters

object[]

This is the set of filters that must match for the hook to trigger

Show child attributes

hooks.filters.type

enum<string>

required

This is the type of filter - currently only "oneOf" is supported

Available options:

oneOf

Maximum string length: 1000

hooks.filters.key

string

required

This is the key to filter on (e.g. "call.endedReason")

Maximum string length: 1000

hooks.filters.oneOf

string[]

required

This is the array of possible values to match against

Maximum string length: 1000

name

string

This is the name of the assistant.

This is required when you want to transfer between assistants in a call.

Maximum string length: 40

voicemailMessage

string

This is the message that the assistant will say if the call is forwarded to voicemail.

If unspecified, it will hang up.

Maximum string length: 1000

endCallMessage

string

This is the message that the assistant will say if it ends the call.

If unspecified, it will hang up without saying anything.

Maximum string length: 1000

endCallPhrases

string[]

This list contains phrases that, if spoken by the assistant, will trigger the call to be hung up. Case insensitive.

Required string length: 2 - 140

compliancePlan

object

Show child attributes

compliancePlan.hipaaEnabled

boolean

When this is enabled, no logs, recordings, or transcriptions will be stored. At the end of the call, you will still receive an end-of-call-report message to store on your server. Defaults to false.

Example:

{ "hipaaEnabled": false }

compliancePlan.pciEnabled

boolean

When this is enabled, the user will be restricted to use PCI-compliant providers, and no logs or transcripts are stored. At the end of the call, you will receive an end-of-call-report message to store on your server. Defaults to false.

Example:

{ "pciEnabled": false }

metadata

object

This is for metadata you want to store on the assistant.

backgroundSpeechDenoisingPlan

object

This enables filtering of noise and background speech while the user is talking.

Features:

Smart denoising using Krisp
Fourier denoising

Smart denoising can be combined with or used independently of Fourier denoising.

Order of precedence:

Smart denoising
Fourier denoising

Show child attributes

backgroundSpeechDenoisingPlan.smartDenoisingPlan

object

Whether smart denoising using Krisp is enabled.

Show child attributes

backgroundSpeechDenoisingPlan.smartDenoisingPlan.enabled

boolean

default:false

Whether smart denoising using Krisp is enabled.

backgroundSpeechDenoisingPlan.fourierDenoisingPlan

object

Whether Fourier denoising is enabled. Note that this is experimental and may not work as expected.

This can be combined with smart denoising, and will be run afterwards.

Show child attributes

backgroundSpeechDenoisingPlan.fourierDenoisingPlan.enabled

boolean

default:false

Whether Fourier denoising is enabled. Note that this is experimental and may not work as expected.

backgroundSpeechDenoisingPlan.fourierDenoisingPlan.mediaDetectionEnabled

boolean

default:true

Whether automatic media detection is enabled. When enabled, the filter will automatically detect consistent background TV/music/radio and switch to more aggressive filtering settings. Only applies when enabled is true.

Example:

true

backgroundSpeechDenoisingPlan.fourierDenoisingPlan.staticThreshold

number

default:-35

Static threshold in dB used as fallback when no baseline is established.

Required range: -80 <= x <= 0

Example:

-35

backgroundSpeechDenoisingPlan.fourierDenoisingPlan.baselineOffsetDb

number

default:-15

How far below the rolling baseline to filter audio, in dB. Lower values (e.g., -10) are more aggressive, higher values (e.g., -20) are more conservative.

Required range: -30 <= x <= -5

Example:

-15

backgroundSpeechDenoisingPlan.fourierDenoisingPlan.windowSizeMs

number

default:3000

Rolling window size in milliseconds for calculating the audio baseline. Larger windows adapt more slowly but are more stable.

Required range: 1000 <= x <= 30000

Example:

3000

backgroundSpeechDenoisingPlan.fourierDenoisingPlan.baselinePercentile

number

default:85

Percentile to use for baseline calculation (1-99). Higher percentiles (e.g., 85) focus on louder speech, lower percentiles (e.g., 50) include quieter speech.

Required range: 1 <= x <= 99

Example:

85

analysisPlan

object

This is the plan for analysis of assistant's calls. Stored in call.analysis.

Show child attributes

analysisPlan.minMessagesThreshold

number

The minimum number of messages required to run the analysis plan. If the number of messages is less than this, analysis will be skipped. @default 2

Required range: x >= 0

analysisPlan.summaryPlan

object

This is the plan for generating the summary of the call. This outputs to call.analysis.summary.

Show child attributes

analysisPlan.summaryPlan.messages

object[]

These are the messages used to generate the summary.

You can customize by providing any messages you want.

Here are the template variables available:

{{transcript}}: The transcript of the call from call.artifact.transcript
{{systemPrompt}}: The system prompt of the call from assistant.model.messages[type=system].content
{{endedReason}}: The ended reason of the call from call.endedReason

analysisPlan.summaryPlan.enabled

boolean

This determines whether a summary is generated and stored in call.analysis.summary. Defaults to true.

Usage:

If you want to disable the summary, set this to false.

@default true

analysisPlan.summaryPlan.timeoutSeconds

number

This is how long the request is tried before giving up. When request times out, call.analysis.summary will be empty.

Usage:

To guarantee the summary is generated, set this value high. Note, this will delay the end of call report in cases where model is slow to respond.

@default 5 seconds

Required range: 1 <= x <= 60

analysisPlan.structuredDataPlan

object

This is the plan for generating the structured data from the call. This outputs to call.analysis.structuredData.

Show child attributes

analysisPlan.structuredDataPlan.messages

object[]

These are the messages used to generate the structured data.

@default: [ { "role": "system", "content": "You are an expert data extractor. You will be given a transcript of a call. Extract structured data per the JSON Schema. DO NOT return anything except the structured data.\n\nJson Schema:\\n{{schema}}\n\nOnly respond with the JSON." }, { "role": "user", "content": "Here is the transcript:\n\n{{transcript}}\n\n. Here is the ended reason of the call:\n\n{{endedReason}}\n\n" } ]

You can customize by providing any messages you want.

Here are the template variables available:

{{transcript}}: the transcript of the call from call.artifact.transcript- {{systemPrompt}}: the system prompt of the call from assistant.model.messages[type=system].content- {{schema}}: the schema of the structured data from structuredDataPlan.schema- {{endedReason}}: the ended reason of the call from call.endedReason

analysisPlan.structuredDataPlan.enabled

boolean

This determines whether structured data is generated and stored in call.analysis.structuredData. Defaults to false.

Usage:

If you want to extract structured data, set this to true and provide a schema.

@default false

analysisPlan.structuredDataPlan.schema

object

This is the schema of the structured data. The output is stored in call.analysis.structuredData.

Complete guide on JSON Schema can be found here.

Show child attributes

analysisPlan.structuredDataPlan.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

analysisPlan.structuredDataPlan.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.

analysisPlan.structuredDataPlan.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.

analysisPlan.structuredDataPlan.schema.description

string

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

analysisPlan.structuredDataPlan.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

analysisPlan.structuredDataPlan.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

analysisPlan.structuredDataPlan.schema.required

string[]

This is a list of properties that are required.

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

analysisPlan.structuredDataPlan.schema.enum

string[]

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

analysisPlan.structuredDataPlan.schema.title

string

This is the title of the schema.

analysisPlan.structuredDataPlan.timeoutSeconds

number

This is how long the request is tried before giving up. When request times out, call.analysis.structuredData will be empty.

Usage:

To guarantee the structured data is generated, set this value high. Note, this will delay the end of call report in cases where model is slow to respond.

@default 5 seconds

Required range: 1 <= x <= 60

analysisPlan.structuredDataMultiPlan

object[]

This is an array of structured data plan catalogs. Each entry includes a key and a plan for generating the structured data from the call. This outputs to call.analysis.structuredDataMulti.

Show child attributes

analysisPlan.structuredDataMultiPlan.key

string

required

This is the key of the structured data plan in the catalog.

analysisPlan.structuredDataMultiPlan.plan

object

required

This is an individual structured data plan in the catalog.

Show child attributes

analysisPlan.structuredDataMultiPlan.plan.messages

object[]

These are the messages used to generate the structured data.

You can customize by providing any messages you want.

Here are the template variables available:

{{transcript}}: the transcript of the call from call.artifact.transcript- {{systemPrompt}}: the system prompt of the call from assistant.model.messages[type=system].content- {{schema}}: the schema of the structured data from structuredDataPlan.schema- {{endedReason}}: the ended reason of the call from call.endedReason

analysisPlan.structuredDataMultiPlan.plan.enabled

boolean

This determines whether structured data is generated and stored in call.analysis.structuredData. Defaults to false.

Usage:

If you want to extract structured data, set this to true and provide a schema.

@default false

analysisPlan.structuredDataMultiPlan.plan.schema

object

This is the schema of the structured data. The output is stored in call.analysis.structuredData.

Complete guide on JSON Schema can be found here.

Show child attributes

analysisPlan.structuredDataMultiPlan.plan.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

analysisPlan.structuredDataMultiPlan.plan.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.

analysisPlan.structuredDataMultiPlan.plan.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.

analysisPlan.structuredDataMultiPlan.plan.schema.description

string

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

analysisPlan.structuredDataMultiPlan.plan.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

analysisPlan.structuredDataMultiPlan.plan.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

analysisPlan.structuredDataMultiPlan.plan.schema.required

string[]

This is a list of properties that are required.

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

analysisPlan.structuredDataMultiPlan.plan.schema.enum

string[]

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

analysisPlan.structuredDataMultiPlan.plan.schema.title

string

This is the title of the schema.

analysisPlan.structuredDataMultiPlan.plan.timeoutSeconds

number

This is how long the request is tried before giving up. When request times out, call.analysis.structuredData will be empty.

Usage:

To guarantee the structured data is generated, set this value high. Note, this will delay the end of call report in cases where model is slow to respond.

@default 5 seconds

Required range: 1 <= x <= 60

analysisPlan.successEvaluationPlan

object

This is the plan for generating the success evaluation of the call. This outputs to call.analysis.successEvaluation.

Show child attributes

analysisPlan.successEvaluationPlan.rubric

enum<string>

This enforces the rubric of the evaluation. The output is stored in call.analysis.successEvaluation.

Options include:

'NumericScale': A scale of 1 to 10.
'DescriptiveScale': A scale of Excellent, Good, Fair, Poor.
'Checklist': A checklist of criteria and their status.
'Matrix': A grid that evaluates multiple criteria across different performance levels.
'PercentageScale': A scale of 0% to 100%.
'LikertScale': A scale of Strongly Agree, Agree, Neutral, Disagree, Strongly Disagree.
'AutomaticRubric': Automatically break down evaluation into several criteria, each with its own score.
'PassFail': A simple 'true' if call passed, 'false' if not.

Default is 'PassFail'.

Available options:

NumericScale,

DescriptiveScale,

Checklist,

Matrix,

PercentageScale,

LikertScale,

AutomaticRubric,

PassFail

analysisPlan.successEvaluationPlan.messages

object[]

These are the messages used to generate the success evaluation.

@default: [ { "role": "system", "content": "You are an expert call evaluator. You will be given a transcript of a call and the system prompt of the AI participant. Determine if the call was successful based on the objectives inferred from the system prompt. DO NOT return anything except the result.\n\nRubric:\\n{{rubric}}\n\nOnly respond with the result." }, { "role": "user", "content": "Here is the transcript:\n\n{{transcript}}\n\n" }, { "role": "user", "content": "Here was the system prompt of the call:\n\n{{systemPrompt}}\n\n. Here is the ended reason of the call:\n\n{{endedReason}}\n\n" } ]

You can customize by providing any messages you want.

Here are the template variables available:

{{transcript}}: the transcript of the call from call.artifact.transcript- {{systemPrompt}}: the system prompt of the call from assistant.model.messages[type=system].content- {{rubric}}: the rubric of the success evaluation from successEvaluationPlan.rubric- {{endedReason}}: the ended reason of the call from call.endedReason

analysisPlan.successEvaluationPlan.enabled

boolean

This determines whether a success evaluation is generated and stored in call.analysis.successEvaluation. Defaults to true.

Usage:

If you want to disable the success evaluation, set this to false.

@default true

analysisPlan.successEvaluationPlan.timeoutSeconds

number

This is how long the request is tried before giving up. When request times out, call.analysis.successEvaluation will be empty.

Usage:

To guarantee the success evaluation is generated, set this value high. Note, this will delay the end of call report in cases where model is slow to respond.

@default 5 seconds

Required range: 1 <= x <= 60

artifactPlan

object

This is the plan for artifacts generated during assistant's calls. Stored in call.artifact.

Show child attributes

artifactPlan.recordingEnabled

boolean

This determines whether assistant's calls are recorded. Defaults to true.

Usage:

If you don't want to record the calls, set this to false.
If you want to record the calls when assistant.hipaaEnabled (deprecated) or assistant.compliancePlan.hipaaEnabled explicity set this to true and make sure to provide S3 or GCP credentials on the Provider Credentials page in the Dashboard.

You can find the recording at call.artifact.recordingUrl and call.artifact.stereoRecordingUrl after the call is ended.

@default true

Example:

true

artifactPlan.recordingFormat

enum<string>

This determines the format of the recording. Defaults to wav;l16.

@default 'wav;l16'

Available options:

wav;l16,

mp3

artifactPlan.videoRecordingEnabled

boolean

This determines whether the video is recorded during the call. Defaults to false. Only relevant for webCall type.

You can find the video recording at call.artifact.videoRecordingUrl after the call is ended.

@default false

Example:

false

artifactPlan.pcapEnabled

boolean

This determines whether the SIP packet capture is enabled. Defaults to true. Only relevant for phone type calls where phone number's provider is cozmox or byo-phone-number.

You can find the packet capture at call.artifact.pcapUrl after the call is ended.

@default true

Example:

true

artifactPlan.pcapS3PathPrefix

string

This is the path where the SIP packet capture will be uploaded. This is only used if you have provided S3 or GCP credentials on the Provider Credentials page in the Dashboard.

If credential.s3PathPrefix or credential.bucketPlan.path is set, this will append to it.

Usage:

If you want to upload the packet capture to a specific path, set this to the path. Example: /my-assistant-captures.
If you want to upload the packet capture to the root of the bucket, set this to /.

@default '/'

Example:

"/pcaps"

artifactPlan.transcriptPlan

object

This is the plan for call.artifact.transcript. To disable, set transcriptPlan.enabled to false.

Show child attributes

artifactPlan.transcriptPlan.enabled

boolean

This determines whether the transcript is stored in call.artifact.transcript. Defaults to true.

@default true

Example:

true

artifactPlan.transcriptPlan.assistantName

string

This is the name of the assistant in the transcript. Defaults to 'AI'.

Usage:

If you want to change the name of the assistant in the transcript, set this. Example, here is what the transcript would look like with assistantName set to 'Buyer':

User: Hello, how are you?
Buyer: I'm fine.
User: Do you want to buy a car?
Buyer: No.

@default 'AI'

artifactPlan.transcriptPlan.userName

string

This is the name of the user in the transcript. Defaults to 'User'.

Usage:

If you want to change the name of the user in the transcript, set this. Example, here is what the transcript would look like with userName set to 'Seller':

Seller: Hello, how are you?
AI: I'm fine.
Seller: Do you want to buy a car?
AI: No.

@default 'User'

artifactPlan.recordingPath

string

This is the path where the recording will be uploaded. This is only used if you have provided S3 or GCP credentials on the Provider Credentials page in the Dashboard.

If credential.s3PathPrefix or credential.bucketPlan.path is set, this will append to it.

Usage:

If you want to upload the recording to a specific path, set this to the path. Example: /my-assistant-recordings.
If you want to upload the recording to the root of the bucket, set this to /.

@default '/'

messagePlan

object

This is the plan for static predefined messages that can be spoken by the assistant during the call, like idleMessages.

Note: firstMessage, voicemailMessage, and endCallMessage are currently at the root level. They will be moved to messagePlan in the future, but will remain backwards compatible.

Show child attributes

messagePlan.idleMessages

string[]

This are the messages that the assistant will speak when the user hasn't responded for idleTimeoutSeconds. Each time the timeout is triggered, a random message will be chosen from this array.

Usage:

If user gets distracted and doesn't respond for a while, this can be used to grab their attention.
If the transcriber doesn't pick up what the user said, this can be used to ask the user to repeat themselves. (From the perspective of the assistant, the conversation is idle since it didn't "hear" any user messages.)

@default null (no idle message is spoken)

Maximum string length: 1000

messagePlan.idleMessageMaxSpokenCount

number

This determines the maximum number of times idleMessages can be spoken during the call.

@default 3

Required range: 1 <= x <= 10

messagePlan.idleMessageResetCountOnUserSpeechEnabled

boolean

This determines whether the idle message count is reset whenever the user speaks.

@default false

messagePlan.idleTimeoutSeconds

number

This is the timeout in seconds before a message from idleMessages is spoken. The clock starts when the assistant finishes speaking and remains active until the user speaks.

@default 10

Required range: 5 <= x <= 60

messagePlan.silenceTimeoutMessage

string

This is the message that the assistant will say if the call ends due to silence.

If unspecified, it will hang up without saying anything.

Maximum string length: 1000

startSpeakingPlan

object

This is the plan for when the assistant should start talking.

You should configure this if you're running into these issues:

The assistant is too slow to start talking after the customer is done speaking.
The assistant is too fast to start talking after the customer is done speaking.
The assistant is so fast that it's actually interrupting the customer.

Show child attributes

startSpeakingPlan.waitSeconds

number

This is how long assistant waits before speaking. Defaults to 0.4.

This is the minimum it will wait but if there is latency is the pipeline, this minimum will be exceeded. This is intended as a stopgap in case the pipeline is moving too fast.

Example:

If model generates tokens and voice generates bytes within 100ms, the pipeline still waits 300ms before outputting speech.

Usage:

If the customer is taking long pauses, set this to a higher value.
If the assistant is accidentally jumping in too much, set this to a higher value.

@default 0.4

Required range: 0 <= x <= 5

Example:

0.4

startSpeakingPlan.smartEndpointingEnabled

deprecated

Example:

false

startSpeakingPlan.smartEndpointingPlan

cozmox · object

This is the plan for smart endpointing. Pick between cozmox smart endpointing or LiveKit smart endpointing (or nothing). We strongly recommend using livekit endpointing when working in English. LiveKit endpointing is not supported in other languages, yet.

If this is set, it will override and take precedence over transcriptionEndpointingPlan. This plan will still be overridden by any matching customEndpointingRules.

cozmox
Livekit
Custom Endpointing Model

Show child attributes

startSpeakingPlan.smartEndpointingPlan.provider

enum<string>

required

This is the provider for the smart endpointing plan.

Available options:

cozmox,

livekit,

custom-endpointing-model

Example:

"cozmox"

startSpeakingPlan.customEndpointingRules

(Assistant · object | Customer · object | Both · object)[]

These are the custom endpointing rules to set an endpointing timeout based on a regex on the customer's speech or the assistant's last message.

Usage:

If you have yes/no questions like "are you interested in a loan?", you can set a shorter timeout.
If you have questions where the customer may pause to look up information like "what's my account number?", you can set a longer timeout.
If you want to wait longer while customer is enumerating a list of numbers, you can set a longer timeout.

These rules have the highest precedence and will override both smartEndpointingPlan and transcriptionEndpointingPlan when a rule is matched.

The rules are evaluated in order and the first one that matches will be used.

Order of precedence for endpointing:

customEndpointingRules (if any match)
smartEndpointingPlan (if set)
transcriptionEndpointingPlan

@default []

Assistant
Customer
Both

Show child attributes

startSpeakingPlan.customEndpointingRules.type

enum<string>

required

This endpointing rule is based on the last assistant message before customer started speaking.

Flow:

Assistant speaks
Customer starts speaking
Customer transcription comes in
This rule is evaluated on the last assistant message
If a match is found based on regex, the endpointing timeout is set to timeoutSeconds

Usage:

If you have yes/no questions in your use case like "are you interested in a loan?", you can set a shorter timeout.
If you have questions where the customer may pause to look up information like "what's my account number?", you can set a longer timeout.

Available options:

assistant

startSpeakingPlan.customEndpointingRules.regex

string

required

This is the regex pattern to match.

Note:

This works by using the RegExp.test method in Node.JS. Eg. /hello/.test("hello there") will return true.

Hot tip:

In JavaScript, escape \ when sending the regex pattern. Eg. "hello\sthere" will be sent over the wire as "hellosthere". Send "hello\\sthere" instead.
RegExp.test does substring matching, so /cat/.test("I love cats") will return true. To do full string matching, send "^cat$".

startSpeakingPlan.customEndpointingRules.timeoutSeconds

number

required

This is the endpointing timeout in seconds, if the rule is matched.

Required range: 0 <= x <= 15

startSpeakingPlan.customEndpointingRules.regexOptions

object[]

These are the options for the regex match. Defaults to all disabled.

@default []

Show child attributes

startSpeakingPlan.customEndpointingRules.regexOptions.type

enum<string>

required

This is the type of the regex option. Options are:

ignore-case: Ignores the case of the text being matched. Add
whole-word: Matches whole words only.
multi-line: Matches across multiple lines.

Available options:

ignore-case,

whole-word,

multi-line

startSpeakingPlan.customEndpointingRules.regexOptions.enabled

boolean

required

This is whether to enable the option.

@default false

startSpeakingPlan.transcriptionEndpointingPlan

object

This determines how a customer speech is considered done (endpointing) using the transcription of customer's speech.

Once an endpoint is triggered, the request is sent to assistant.model.

Note: This plan is only used if smartEndpointingPlan is not set. If both are provided, smartEndpointingPlan takes precedence. This plan will also be overridden by any matching customEndpointingRules.

Show child attributes

startSpeakingPlan.transcriptionEndpointingPlan.onPunctuationSeconds

number

The minimum number of seconds to wait after transcription ending with punctuation before sending a request to the model. Defaults to 0.1.

This setting exists because the transcriber punctuates the transcription when it's more confident that customer has completed a thought.

@default 0.1

Required range: 0 <= x <= 3

Example:

0.1

startSpeakingPlan.transcriptionEndpointingPlan.onNoPunctuationSeconds

number

The minimum number of seconds to wait after transcription ending without punctuation before sending a request to the model. Defaults to 1.5.

This setting exists to catch the cases where the transcriber was not confident enough to punctuate the transcription, but the customer is done and has been silent for a long time.

@default 1.5

Required range: 0 <= x <= 3

Example:

1.5

startSpeakingPlan.transcriptionEndpointingPlan.onNumberSeconds

number

The minimum number of seconds to wait after transcription ending with a number before sending a request to the model. Defaults to 0.4.

This setting exists because the transcriber will sometimes punctuate the transcription ending with a number, even though the customer hasn't uttered the full number. This happens commonly for long numbers when the customer reads the number in chunks.

@default 0.5

Required range: 0 <= x <= 3

Example:

0.5

stopSpeakingPlan

object

This is the plan for when assistant should stop talking on customer interruption.

You should configure this if you're running into these issues:

The assistant is too slow to recognize customer's interruption.
The assistant is too fast to recognize customer's interruption.
The assistant is getting interrupted by phrases that are just acknowledgments.
The assistant is getting interrupted by background noises.
The assistant is not properly stopping -- it starts talking right after getting interrupted.

Show child attributes

stopSpeakingPlan.numWords

number

This is the number of words that the customer has to say before the assistant will stop talking.

Words like "stop", "actually", "no", etc. will always interrupt immediately regardless of this value.

Words like "okay", "yeah", "right" will never interrupt.

When set to 0, voiceSeconds is used in addition to the transcriptions to determine the customer has started speaking.

Defaults to 0.

@default 0

Required range: 0 <= x <= 10

Example:

0

stopSpeakingPlan.voiceSeconds

number

This is the seconds customer has to speak before the assistant stops talking. This uses the VAD (Voice Activity Detection) spike to determine if the customer has started speaking.

Considerations:

A lower value might be more responsive but could potentially pick up non-speech sounds.
A higher value reduces false positives but might slightly delay the detection of speech onset.

This is only used if numWords is set to 0.

Defaults to 0.2

@default 0.2

Required range: 0 <= x <= 0.5

Example:

0.2

stopSpeakingPlan.backoffSeconds

number

This is the seconds to wait before the assistant will start talking again after being interrupted.

Defaults to 1.

@default 1

Required range: 0 <= x <= 10

Example:

1

stopSpeakingPlan.acknowledgementPhrases

string[]

These are the phrases that will never interrupt the assistant, even if numWords threshold is met. These are typically acknowledgement or backchanneling phrases.

Maximum string length: 240

Example:

[
  "i understand",
  "i see",
  "i got it",
  "i hear you",
  "im listening",
  "im with you",
  "right",
  "okay",
  "ok",
  "sure",
  "alright",
  "got it",
  "understood",
  "yeah",
  "yes",
  "uh-huh",
  "mm-hmm",
  "gotcha",
  "mhmm",
  "ah",
  "yeah okay",
  "yeah sure"
]

stopSpeakingPlan.interruptionPhrases

string[]

These are the phrases that will always interrupt the assistant immediately, regardless of numWords. These are typically phrases indicating disagreement or desire to stop.

Maximum string length: 240

Example:

[
  "stop",
  "shut",
  "up",
  "enough",
  "quiet",
  "silence",
  "but",
  "dont",
  "not",
  "no",
  "hold",
  "wait",
  "cut",
  "pause",
  "nope",
  "nah",
  "nevermind",
  "never",
  "bad",
  "actually"
]

monitorPlan

object

This is the plan for real-time monitoring of the assistant's calls.

Usage:

To enable live listening of the assistant's calls, set monitorPlan.listenEnabled to true.
To enable live control of the assistant's calls, set monitorPlan.controlEnabled to true.

Show child attributes

monitorPlan.listenEnabled

boolean

This determines whether the assistant's calls allow live listening. Defaults to true.

Fetch call.monitor.listenUrl to get the live listening URL.

@default true

Example:

false

monitorPlan.listenAuthenticationEnabled

boolean

This enables authentication on the call.monitor.listenUrl.

If listenAuthenticationEnabled is true, the call.monitor.listenUrl will require an Authorization: Bearer <cozmox-public-api-key> header.

@default false

Example:

false

monitorPlan.controlEnabled

boolean

This determines whether the assistant's calls allow live control. Defaults to true.

Fetch call.monitor.controlUrl to get the live control URL.

To use, send any control message via a POST request to call.monitor.controlUrl. Here are the types of controls supported: https://docs.cozmox.ai/api-reference/messages/client-inbound-message

@default true

Example:

false

monitorPlan.controlAuthenticationEnabled

boolean

This enables authentication on the call.monitor.controlUrl.

If controlAuthenticationEnabled is true, the call.monitor.controlUrl will require an Authorization: Bearer <cozmox-public-api-key> header.

@default false

Example:

false

credentialIds

string[]

These are the credentials that will be used for the assistant calls. By default, all the credentials are available for use in the call but you can provide a subset using this.

server

object

This is where cozmox will send webhooks. You can find all webhooks available along with their shape in ServerMessage schema.

The order of precedence is:

assistant.server.url
phoneNumber.serverUrl
org.serverUrl

Show child attributes

server.timeoutSeconds

number

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

@default 20

Required range: 1 <= x <= 300

Example:

20

server.url

string

This is where the request will be sent.

server.headers

object

These are the headers to include in the request.

Each key-value pair represents a header name and its value.

server.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

server.backoffPlan.type

object

required

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

@default fixed

Example:

"fixed"

server.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

server.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

keypadInputPlan

object

Show child attributes

keypadInputPlan.enabled

boolean

This keeps track of whether the user has enabled keypad input. By default, it is off.

@default false

keypadInputPlan.timeoutSeconds

number

This is the time in seconds to wait before processing the input. If the input is not received within this time, the input will be ignored. If set to "off", the input will be processed when the user enters a delimiter or immediately if no delimiter is used.

@default 2

Required range: 0 <= x <= 10

keypadInputPlan.delimiters

enum<string>

This is the delimiter(s) that will be used to process the input. Can be '#', '*', or an empty array.

Available options:

#,

*,

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

Query Parameters

Response