Skip to content
RevoxRevox
Get started
API Reference
Assistants

Create an assistant

client.assistants.create(AssistantCreateParams { name, prompt, background_sound, 45 more } body, RequestOptionsoptions?): AssistantCreateResponse { assistant }
POST/assistants

Create a new AI assistant with a custom prompt, voice, and behavior configuration. Assistants define how the AI agent behaves during calls, including the system prompt given to the LLM, the first sentence spoken, the voice provider and voice ID (Cartesia or ElevenLabs), and end-of-call behavior. Once created, reference the assistant by its ID when placing calls.

ParametersExpand Collapse
body: AssistantCreateParams { name, prompt, background_sound, 45 more }
name: string
prompt: string

The prompt to use for the call. This will be given to the LLM (gpt-4.1)

background_sound?: "audio/office.ogg" | null

Ambient background sound to play during the call. null/omitted disables it.

background_sound_volume?: number

Volume of the ambient background sound (0 = silent, 1 = max).

minimum0
maximum1
cal?: Cal | null
connection_id: string

The connection ID representing the link between your Cal.com account and Revox.

event_type_id: string

The ID of the Cal.com event type to schedule. (eg: 7081322)

calendly?: Calendly | null
connection_id: string

The connection ID representing the link between your Calendly account and Revox.

event_type_id: string

The event type ID representing the event type to schedule. (eg: https://api.calendly.com/event_types/b2330295-2a91-4a1d-bb73-99e7707663d5)

call_retry_config?: CallRetryConfig

Configuration for call retry behavior including time windows, delays, and max iterations. If not provided, defaults will be used.

allowed_days: Array<"monday" | "tuesday" | "wednesday" | 4 more>

Days of the week when calls are allowed, in the recipient’s timezone. Default: Monday through Friday.

One of the following:
"monday"
"tuesday"
"wednesday"
"thursday"
"friday"
"saturday"
"sunday"
call_twice_in_a_row: boolean

If true and max_retry_attempts >= 2, attempt #2 fires immediately (skipping retry_delay_seconds) when attempt #1 didn’t reach a human. Calling-window/allowed-days checks still apply. Only affects the 1→2 transition. Default: false.

calling_windows: Array<CallingWindow>
calling_window_end_time: string

End time for the calling window in the recipient’s timezone (or timezone_override if provided). Format: ‘HH:mm’ (24-hour) or ‘H:mma’ (12-hour). Examples: ‘17:00’, ‘6pm’. Default: ‘18:00’.

calling_window_start_time: string

Start time for the calling window in the recipient’s timezone (or timezone_override if provided). Format: ‘HH:mm’ (24-hour) or ‘H:mma’ (12-hour). Examples: ‘09:00’, ‘10am’. Default: ‘10:00’.

retry_delay_seconds: unknown

Delay between retry attempts in seconds. Values below the 15-minute minimum are raised to it: a shorter delay means calling someone again minutes after they declined. For one deliberate immediate second dial, use call_twice_in_a_row. Default: 7200 (2 hours).

max_retry_attempts: number

Maximum number of call retry attempts. Default: 3.

exclusiveMinimum0
maximum9007199254740991
timezone?: string | null

Optional IANA timezone identifier to override the automatic timezone detection from phone number. If not provided, timezone is determined from the recipient’s phone number country code. Examples: ‘America/New_York’, ‘Europe/Paris’.

cartesia_dictionary_pronunciation_id?: string | null

Optional Cartesia pronunciation dictionary ID to use for this assistant’s calls. Set null to unlink it.

minLength1
custom_tools?: Array<CustomTool> | null

Custom API tools the assistant can call during conversations. Each tool defines an HTTP endpoint with variable substitution.

body_template: string | null

JSON body template for the request. Use quoted {{variable}} placeholders (e.g. “{{name}}”) for dynamic values

description: string

Human-readable description of what the tool does, used by the LLM to decide when to call it

minLength1
headers: Array<Header>

HTTP headers to include in the request. Values support {{variable}} placeholders

key: string
minLength1
value: string
input_schema: Array<InputSchema>

Schema defining the parameters the LLM should extract from the conversation to pass to this tool

name: string
minLength1
required: boolean
type: "string" | "number" | "boolean" | 3 more
One of the following:
"string"
"number"
"boolean"
"enum"
"date"
"datetime"
description?: string
enum_options?: Array<string>
method: "GET" | "POST" | "PUT" | 2 more

HTTP method to use when calling the API endpoint

One of the following:
"GET"
"POST"
"PUT"
"PATCH"
"DELETE"
name: string

Unique tool name in lowercase_snake_case (e.g. check_inventory)

minLength1
query_params: Array<QueryParam>

Query string parameters appended to the URL. Values support {{variable}} placeholders

key: string
minLength1
value: string
url: string

Full URL of the API endpoint. Supports {{variable}} placeholders for dynamic values

minLength1
end_of_call_sentence?: string

Optional message to say when the agent decides to end the call.

first_sentence?: string

The first sentence to use for the call. This will be given to the LLM

first_sentence_delay_ms?: number

Delay in milliseconds before speaking the first sentence. Default: 400.

minimum0
maximum9007199254740991
first_sentence_mode?: "generated" | "static" | "none"

How the first sentence should be handled. “generated” means the LLM will generate a response based on the first_sentence instruction. “static” means the first_sentence will be spoken exactly as provided. “none” means the agent will not speak first and will wait for the user.

One of the following:
"generated"
"static"
"none"
from_phone_number?: string | null

Override the default outbound phone number for calls placed with this assistant. Must be a phone number owned by the organization in E.164 format (e.g. +1234567890). When null, the organization’s default phone number is used.

hubspot?: Hubspot | null

HubSpot Meetings config. When set with at least one meeting link, the agent can read a rep’s real availability and book the meeting natively in HubSpot during the call.

connection_id: string

The Nango connection ID linking the org’s HubSpot account to Revox.

precall_lookup_enabled: boolean

Resolve the caller against HubSpot contacts before answering an inbound call, filling the contact_* prompt variables (contact_name, contact_owner, contact_lead_status, contact_has_open_deal). Off by default: it costs API calls before the phone is picked up.

post_call_sync?: PostCallSync { enabled, field_mapping }

Sends call data back to HubSpot after the call. Off until set: connecting HubSpot to book meetings must not start writing to the CRM. Always present in responses; omit it on update to leave the current setting untouched.

enabled: boolean

Records calls in HubSpot after they end: the contact is created or updated from the phone number and the call is logged on its timeline. By default every call a person answered is recorded. When the post-call prompt talks about the CRM (in plain words or by mentioning the crm_push_call tool), the post-call agent decides instead which calls are recorded and what the logged call says.

field_mapping: Array<FieldMapping>

Maps extracted call fields (structured_output / prompt variables) onto HubSpot contact properties.

hubspot_property: string

Destination HubSpot contact property, by internal name (e.g. ‘email’, ‘company’, or a custom ‘budget’).

minLength1
source: string

Source key to read from the call: a structured_output field name, falling back to a prompt variable of the same name.

minLength1
human_transfer_mode?: "warm" | "cold" | null

When transfer_destinations is non-empty: “warm” (AI bridges) or “cold” (SIP REFER; trunk must allow REFER/PSTN). Omit or null when transfer is disabled.

One of the following:
"warm"
"cold"
ivr_navigation_enabled?: boolean

Enable IVR navigation tools. When enabled, the assistant can send DTMF tones and skip turns to navigate phone menus.

krisp_viva_filter_enabled?: boolean

When true, the agent’s noise-cancellation filter is Krisp VIVA Tel instead of the legacy BVCTelephony. Default false.

llm_model?: Recommended { type } | UnionMember1 { name, type } | UnionMember2 { openrouter_model_id, openrouter_provider, type } | 4 more
One of the following:
Recommended { type }
type: "recommended"

The LLM Revox currently recommends for voice agents, chosen server-side and upgraded without any change on your side. No per-assistant configuration.

UnionMember1 { name, type }
name: "gpt-4.1" | "ministral-3-8b-instruct"
One of the following:
"gpt-4.1"
"ministral-3-8b-instruct"
type: "dedicated-instance"
UnionMember2 { openrouter_model_id, openrouter_provider, type }
openrouter_model_id: string

The model ID to use from OpenRouter. eg: openai/gpt-4.1

openrouter_provider: string

The provider to use from OpenRouter. eg: nebius, openai, azure, etc.

type: "openrouter"

Use a model from OpenRouter.

UnionMember3 { api_key, api_url, model_name, type }
api_key: string

API key sent as Bearer token to the custom endpoint.

minLength1
api_url: string

Base URL for the OpenAI-compatible API, e.g. https://api.together.xyz/v1

formaturi
model_name: string

Model name as expected by the provider, e.g. meta-llama/llama-3-70b

minLength1
type: "custom"

OpenAI-compatible chat completions API (bring your own endpoint and key).

Type { type }
type: "gemma-4-31b-racing"

gemma-4-31b raced between two pinned OpenRouter endpoints (modelrun/fp4 and crusoe/bf16), first chunk wins. Served with the server-side OPENROUTER_API_KEY; no per-assistant configuration.

UnionMember5 { model_name, type, reasoning_effort }
model_name: string

Fireworks model id, e.g. accounts/fireworks/models/qwen3-235b-a22b or a dedicated deployment id.

minLength1
type: "fireworks"

Fireworks AI model, served with the server-side FIREWORKS_API_KEY (no key stored per-assistant).

reasoning_effort?: "none" | "low" | "medium" | "high"

Reasoning effort sent with each request. Hybrid-reasoning models (e.g. gemma-4-31b) think by default, which adds latency and can eat the whole token budget before any speakable text: voice agents want ‘none’. Omit for models that reject the knob.

One of the following:
"none"
"low"
"medium"
"high"
UnionMember6 { provider, realtime_model_id, type, realtime_voice_id }
provider: "openai" | "google"

The provider to use from Realtime. eg: openai, google.

One of the following:
"openai"
"google"
realtime_model_id: string

The model ID to use from Realtime. eg: gpt-4.1

type: "realtime"

Use a model from Realtime.

realtime_voice_id?: string

Output voice for the realtime provider (e.g. OpenAI: marin; Gemini: Puck).

minLength1
logo_url?: string | null

Public URL of the brand logo shown on the assistant’s demo page. Upload a new logo via POST /assistants/:id/logo. Set explicitly to null to clear it.

formaturi
max_call_duration_secs?: number

The maximum duration of the call in seconds. This is the maximum time the call will be allowed to run.

max_duration_end_message?: string | null

Optional message the agent will say, without being interruptible, when the call reaches its max duration. Kept short so it fits inside the farewell buffer. If not set, the call ends silently.

maxLength150
position?: Position | null

Canvas position of this assistant’s node in its multi-step flow editor.

x: number
y: number
post_call_prompt?: string | null

Instructions the agent follows once the call has ended: who to email, when to text, what to post on Slack or Teams. Plain language, no template syntax. Empty or null means no post-call agent runs.

precall_lookup_headers?: Array<PrecallLookupHeader> | null

HTTP headers sent with the pre-call lookup request, e.g. an API key. Null or empty when the endpoint needs none.

key: string
maxLength200
value: string
minLength1
maxLength4000
precall_lookup_url?: string | null

Inbound calls only. URL fetched over HTTP GET right before the call is answered, with {{phone}} replaced by the caller’s number in E.164 format (URL-encoded), to fill the {{variable}} placeholders the assistant declares. It answers either {"prompt_variables": {...}} or a flat JSON object whose top-level fields are the variables. The call is always answered: if the endpoint fails, takes more than 3 seconds, answers 404 or leaves a variable out, the missing variables are marked as not provided. Must be an http(s) URL containing {{phone}}. When null, no lookup is performed.

maxLength2000
slack?: Slack | null

Slack notification config. When set, posts a message to the chosen channel after a call ends with one of the configured outcomes.

channels: Array<Channel>

The Slack channels the post-call agent may post to. It resolves the channel it was told to use against this list and cannot reach any other.

id: string

The Slack channel ID (e.g. ‘C01234567’).

name?: string | null

Human-readable Slack channel name, cached for display in the UI and given to the LLM when the agent prompt routes by channel name.

connection_id: string

The Nango connection ID linking the org’s Slack workspace to Revox.

start_step_name?: string | null

Name of a multi-step flow’s start step. Defaults to the assistant’s name.

maxLength255
structured_output_config?: Array<StructuredOutputConfig>

The structured output config to use for the call. This is used to extract the data from the call (like email, name, company name, etc.).

name: string
minLength1
required: boolean
type: "string" | "number" | "boolean" | 3 more
One of the following:
"string"
"number"
"boolean"
"enum"
"date"
"datetime"
description?: string
enum_options?: Array<string>
structured_output_prompt?: string | null

Custom prompt for structured data extraction. If not provided, a default prompt is used. Available variables: {{transcript}}, {{call_direction}}, {{user_phone_number}}, {{agent_phone_number}}.

stt_bvc_filter_enabled?: boolean

When false, the agent transcribes the raw caller track instead of the BVC noise-cancellation output. Default true.

stt_context?: SttContext | null

Assistant-level speech-to-text context: structured general key/value pairs plus a list of domain terms. Prompt-derived context is merged in without replacing existing entries.

general: Array<General>
key: string
minLength1
value: string
minLength1
terms: Array<string>
stt_endpoint_latency_level?: number | null

Soniox endpoint latency adjustment level (0 to 3). Higher values reduce endpoint latency at a slight accuracy cost. Null or omitted: Soniox default.

minimum0
maximum3
stt_endpoint_sensitivity?: number | null

Soniox endpoint sensitivity (-1 to 1). Higher values finalize transcripts sooner. Null or omitted: Soniox default.

minimum-1
maximum1
stt_model?: "stt-rt-v4" | "stt-rt-v5"

Transcriber (speech-to-text) model. Defaults to the newest Soniox realtime model when omitted.

One of the following:
"stt-rt-v4"
"stt-rt-v5"
teams?: Teams | null

Microsoft Teams config. When set with at least one channel, the post-call agent can post to those channels when the post-call instructions ask for it.

channels: Array<Channel>

The Teams channels the post-call agent may post to. It resolves the channel it was told to use against this list and cannot reach any other.

id: string

The Microsoft Teams channel ID (e.g. ‘19:561fbdbb…@thread.tacv2’).

team_id: string

The ID of the team the channel belongs to. Needed to post.

name?: string | null

Human-readable channel name, cached for display in the UI and given to the LLM when the agent prompt routes by channel name.

team_name?: string | null

Human-readable team name. Channel names repeat across teams (every team has a ‘General’), so the team name is what tells two of them apart.

connection_id: string

The Nango connection ID linking a Microsoft Teams account to Revox. Messages are posted as that account.

thinking_sound?: "city-ambience.ogg" | "forest-ambience.ogg" | "office-ambience.ogg" | 4 more | null

Audio clip to play while the agent is processing a response. One of the built-in LiveKit audio clips; null/omitted disables it.

One of the following:
"city-ambience.ogg"
"forest-ambience.ogg"
"office-ambience.ogg"
"crowded-room.ogg"
"keyboard-typing.ogg"
"keyboard-typing2.ogg"
"hold_music.ogg"
thinking_sound_probability?: number

Probability [0..1] that the thinking sound plays on any given turn; otherwise the agent is silent while thinking.

minimum0
maximum1
thinking_sound_volume?: number

Volume of the thinking sound (0 = silent, 1 = max).

minimum0
maximum1
transfer_destinations?: Array<TransferDestination> | null

Where calls can be transferred to when users ask to speak to a human. With a single entry the assistant always transfers there; with several, it picks one at transfer time by applying the routing rules written in the assistant’s own prompt (which refer to the destination labels). Empty or null disables transfer.

label: string

Human-meaningful name for this destination (e.g. “Sales”). The assistant’s prompt refers to these labels when describing who to transfer to.

minLength1
maxLength60
phone_number: string

Destination phone number in E.164 format (e.g. +1234567890).

type?: "standalone" | "multi-step" | "sub-assistant"

Assistant kind. ‘standalone’ (default) is a normal assistant, ‘multi-step’ orchestrates a flow of sub-assistants, ‘sub-assistant’ is a step inside a multi-step flow (hidden from the assistants list). Flow transitions are managed via the /assistants/:id/edges endpoints, not on the assistant itself.

One of the following:
"standalone"
"multi-step"
"sub-assistant"
voice?: Voice

The voice to use for the call. You can get the list of voices using the /voices endpoint

id: string

The ID of the voice.

minLength1
provider: "cartesia" | "elevenlabs" | "gradium"

The provider of the voice.

One of the following:
"cartesia"
"elevenlabs"
"gradium"
model?: "sonic-3" | "sonic-3.5" | "sonic-3.6"

Cartesia TTS model (Cartesia only). Defaults to sonic-3.6 when omitted. Ignored for other providers.

One of the following:
"sonic-3"
"sonic-3.5"
"sonic-3.6"
speed?: number

The speed of the voice. Range depends on provider: Cartesia 0.6–1.5, ElevenLabs 0.7–1.2, Gradium 0.6–1.5. Default is 1.0.

minimum0.6
maximum1.5
volume?: number

Volume of the voice (Cartesia only). 0.5–2.0, default 1.0. Ignored for other providers.

minimum0.5
maximum2
voice_languages?: Array<VoiceLanguage> | null

Extra languages for a multilingual assistant, each with its own voice. Calls pick one through their language value, else the phone number’s country; other calls use the assistant’s voice.

language: "en" | "fr" | "es" | 5 more

The language contacts are called in with this voice.

One of the following:
"en"
"fr"
"es"
"de"
"it"
"pt"
"ru"
"zh"
voice: Voice { id, provider, model, 2 more }

The voice used for contacts whose language is this language.

id: string

The ID of the voice.

minLength1
provider: "cartesia" | "elevenlabs" | "gradium"

The provider of the voice.

One of the following:
"cartesia"
"elevenlabs"
"gradium"
model?: "sonic-3" | "sonic-3.5" | "sonic-3.6"

Cartesia TTS model (Cartesia only). Defaults to sonic-3.6 when omitted. Ignored for other providers.

One of the following:
"sonic-3"
"sonic-3.5"
"sonic-3.6"
speed?: number

The speed of the voice. Range depends on provider: Cartesia 0.6–1.5, ElevenLabs 0.7–1.2, Gradium 0.6–1.5. Default is 1.0.

minimum0.6
maximum1.5
volume?: number

Volume of the voice (Cartesia only). 0.5–2.0, default 1.0. Ignored for other providers.

minimum0.5
maximum2
voicemail_message?: string | null

If set, when voicemail is detected the agent will speak this message then hang up; if null, hang up immediately.

warm_transfer_summary_instructions?: string | null

When using warm transfer: extra instructions for the supervisor handoff summary. If null or empty, the API uses the product default briefing when the call is loaded for the agent.

warm_transfer_voice_speed?: number | null

When using warm transfer: voice speed used only while the AI briefs the human colleague. Same range as voice.speed. Omit or null to brief at the assistant’s voice speed.

minimum0.6
maximum1.5
webhook_url?: string

The webhook URL to call when the call is completed.

zoho?: Zoho | null

Zoho CRM integration config. When set, upserts the prospect (keyed on phone) into the chosen module and attaches a Note with the call summary after a call ends with one of the configured outcomes.

connection_id: string

The Nango connection ID linking the org’s Zoho CRM account to Revox.

field_mapping: Array<FieldMapping>

Maps extracted call fields (structured_output / prompt variables) onto Zoho field API names on the upserted record.

source: string

Source key to read from the call: a structured_output field name, falling back to a prompt variable of the same name.

minLength1
zoho_field: string

Destination Zoho field API name on the upserted record (e.g. ‘Email’, ‘Company’, or a custom ‘Budget__c’).

minLength1
log_call_activity: boolean

When true, also log the call as a record in Zoho’s Calls module (related to the upserted prospect via Who_Id).

module: string

Zoho module the prospect record is upserted into (e.g. ‘Leads’ or ‘Contacts’).

minLength1
template?: string | null

Optional Note body template. Supports {{summary}}, {{outcome}}, {{phone}}, {{call_url}}, {{assistant_name}}, {{campaign_name}}, {{transcript}}, plus prompt_variables and structured_output keys. When null/empty a default note (outcome + summary + auto-listed extracted fields) is used.

ReturnsExpand Collapse
AssistantCreateResponse { assistant }
assistant: Assistant { id, background_sound, background_sound_volume, 52 more }
id: string
background_sound: "audio/office.ogg" | null

Ambient background sound to play during the call. null disables it.

background_sound_volume: number

Volume of the ambient background sound (0 = silent, 1 = max).

minimum0
maximum1
cal: Cal | null
connection_id: string

The connection ID representing the link between your Cal.com account and Revox.

event_type_id: string

The ID of the Cal.com event type to schedule. (eg: 7081322)

calendly: Calendly | null
connection_id: string

The connection ID representing the link between your Calendly account and Revox.

event_type_id: string

The event type ID representing the event type to schedule. (eg: https://api.calendly.com/event_types/b2330295-2a91-4a1d-bb73-99e7707663d5)

call_retry_config: CallRetryConfig | null

Configuration for call retry behavior including time windows, delays, and max iterations. If not provided, defaults will be used.

allowed_days: Array<"monday" | "tuesday" | "wednesday" | 4 more>

Days of the week when calls are allowed, in the recipient’s timezone. Default: Monday through Friday.

One of the following:
"monday"
"tuesday"
"wednesday"
"thursday"
"friday"
"saturday"
"sunday"
call_twice_in_a_row: boolean

If true and max_retry_attempts >= 2, attempt #2 fires immediately (skipping retry_delay_seconds) when attempt #1 didn’t reach a human. Calling-window/allowed-days checks still apply. Only affects the 1→2 transition. Default: false.

calling_windows: Array<CallingWindow>
calling_window_end_time: string

End time for the calling window in the recipient’s timezone (or timezone_override if provided). Format: ‘HH:mm’ (24-hour) or ‘H:mma’ (12-hour). Examples: ‘17:00’, ‘6pm’. Default: ‘18:00’.

calling_window_start_time: string

Start time for the calling window in the recipient’s timezone (or timezone_override if provided). Format: ‘HH:mm’ (24-hour) or ‘H:mma’ (12-hour). Examples: ‘09:00’, ‘10am’. Default: ‘10:00’.

retry_delay_seconds: unknown

Delay between retry attempts in seconds. Values below the 15-minute minimum are raised to it: a shorter delay means calling someone again minutes after they declined. For one deliberate immediate second dial, use call_twice_in_a_row. Default: 7200 (2 hours).

max_retry_attempts: number

Maximum number of call retry attempts. Default: 3.

exclusiveMinimum0
maximum9007199254740991
timezone?: string | null

Optional IANA timezone identifier to override the automatic timezone detection from phone number. If not provided, timezone is determined from the recipient’s phone number country code. Examples: ‘America/New_York’, ‘Europe/Paris’.

cartesia_dictionary_pronunciation_id: string | null

Optional Cartesia pronunciation dictionary ID linked to this assistant.

created_at: unknown
custom_tools: Array<CustomTool> | null
body_template: string | null

JSON body template for the request. Use quoted {{variable}} placeholders (e.g. “{{name}}”) for dynamic values

description: string

Human-readable description of what the tool does, used by the LLM to decide when to call it

minLength1
headers: Array<Header>

HTTP headers to include in the request. Values support {{variable}} placeholders

key: string
minLength1
value: string
input_schema: Array<InputSchema>

Schema defining the parameters the LLM should extract from the conversation to pass to this tool

name: string
minLength1
required: boolean
type: "string" | "number" | "boolean" | 3 more
One of the following:
"string"
"number"
"boolean"
"enum"
"date"
"datetime"
description?: string
enum_options?: Array<string>
method: "GET" | "POST" | "PUT" | 2 more

HTTP method to use when calling the API endpoint

One of the following:
"GET"
"POST"
"PUT"
"PATCH"
"DELETE"
name: string

Unique tool name in lowercase_snake_case (e.g. check_inventory)

minLength1
query_params: Array<QueryParam>

Query string parameters appended to the URL. Values support {{variable}} placeholders

key: string
minLength1
value: string
url: string

Full URL of the API endpoint. Supports {{variable}} placeholders for dynamic values

minLength1
end_of_call_sentence: string | null
first_sentence: string | null
first_sentence_delay_ms: number

Delay in milliseconds before speaking the first sentence. Default: 400.

minimum-9007199254740991
maximum9007199254740991
first_sentence_mode: "generated" | "static" | "none"
One of the following:
"generated"
"static"
"none"
from_phone_number: string | null

Override the default outbound phone number for calls placed with this assistant. When null, the organization’s default phone number is used.

hubspot: Hubspot | null
connection_id: string

The Nango connection ID linking the org’s HubSpot account to Revox.

precall_lookup_enabled: boolean

Resolve the caller against HubSpot contacts before answering an inbound call, filling the contact_* prompt variables (contact_name, contact_owner, contact_lead_status, contact_has_open_deal). Off by default: it costs API calls before the phone is picked up.

post_call_sync?: PostCallSync { enabled, field_mapping }

Sends call data back to HubSpot after the call. Off until set: connecting HubSpot to book meetings must not start writing to the CRM. Always present in responses; omit it on update to leave the current setting untouched.

enabled: boolean

Records calls in HubSpot after they end: the contact is created or updated from the phone number and the call is logged on its timeline. By default every call a person answered is recorded. When the post-call prompt talks about the CRM (in plain words or by mentioning the crm_push_call tool), the post-call agent decides instead which calls are recorded and what the logged call says.

field_mapping: Array<FieldMapping>

Maps extracted call fields (structured_output / prompt variables) onto HubSpot contact properties.

hubspot_property: string

Destination HubSpot contact property, by internal name (e.g. ‘email’, ‘company’, or a custom ‘budget’).

minLength1
source: string

Source key to read from the call: a structured_output field name, falling back to a prompt variable of the same name.

minLength1
human_transfer_mode: "warm" | "cold" | null

Warm or cold transfer when transfer_destinations is non-empty; null when transfer is not configured.

One of the following:
"warm"
"cold"
ivr_navigation_enabled: boolean

Enable IVR navigation tools. When enabled, the assistant can send DTMF tones and skip turns to navigate phone menus.

krisp_viva_filter_enabled: boolean

When true, the agent’s noise-cancellation filter is Krisp VIVA Tel instead of the legacy BVCTelephony.

llm_model: Recommended { type } | UnionMember1 { name, type } | UnionMember2 { openrouter_model_id, openrouter_provider, type } | 4 more
One of the following:
Recommended { type }
type: "recommended"

The LLM Revox currently recommends for voice agents, chosen server-side and upgraded without any change on your side. No per-assistant configuration.

UnionMember1 { name, type }
name: "gpt-4.1" | "ministral-3-8b-instruct"
One of the following:
"gpt-4.1"
"ministral-3-8b-instruct"
type: "dedicated-instance"
UnionMember2 { openrouter_model_id, openrouter_provider, type }
openrouter_model_id: string

The model ID to use from OpenRouter. eg: openai/gpt-4.1

openrouter_provider: string

The provider to use from OpenRouter. eg: nebius, openai, azure, etc.

type: "openrouter"

Use a model from OpenRouter.

UnionMember3 { api_key, api_url, model_name, type }
api_key: string

API key sent as Bearer token to the custom endpoint.

minLength1
api_url: string

Base URL for the OpenAI-compatible API, e.g. https://api.together.xyz/v1

formaturi
model_name: string

Model name as expected by the provider, e.g. meta-llama/llama-3-70b

minLength1
type: "custom"

OpenAI-compatible chat completions API (bring your own endpoint and key).

Type { type }
type: "gemma-4-31b-racing"

gemma-4-31b raced between two pinned OpenRouter endpoints (modelrun/fp4 and crusoe/bf16), first chunk wins. Served with the server-side OPENROUTER_API_KEY; no per-assistant configuration.

UnionMember5 { model_name, type, reasoning_effort }
model_name: string

Fireworks model id, e.g. accounts/fireworks/models/qwen3-235b-a22b or a dedicated deployment id.

minLength1
type: "fireworks"

Fireworks AI model, served with the server-side FIREWORKS_API_KEY (no key stored per-assistant).

reasoning_effort?: "none" | "low" | "medium" | "high"

Reasoning effort sent with each request. Hybrid-reasoning models (e.g. gemma-4-31b) think by default, which adds latency and can eat the whole token budget before any speakable text: voice agents want ‘none’. Omit for models that reject the knob.

One of the following:
"none"
"low"
"medium"
"high"
UnionMember6 { provider, realtime_model_id, type, realtime_voice_id }
provider: "openai" | "google"

The provider to use from Realtime. eg: openai, google.

One of the following:
"openai"
"google"
realtime_model_id: string

The model ID to use from Realtime. eg: gpt-4.1

type: "realtime"

Use a model from Realtime.

realtime_voice_id?: string

Output voice for the realtime provider (e.g. OpenAI: marin; Gemini: Puck).

minLength1
logo_url: string | null

Public URL of the brand logo shown on the assistant’s demo page. Null when unset.

max_call_duration_secs: number

The maximum duration of the call in seconds. This is the maximum time the call will be allowed to run.

max_duration_end_message: string | null

Optional message the agent will say, without being interruptible, when the call reaches its max duration. Kept short so it fits inside the farewell buffer. If null, the call ends silently.

maxLength150
name: string
organization_id: string
position: Position | null
x: number
y: number
post_call_prompt: string | null
precall_lookup_headers: Array<PrecallLookupHeader> | null

HTTP headers sent with the pre-call lookup request. Null when none are configured.

key: string
maxLength200
value: string
minLength1
maxLength4000
precall_lookup_url: string | null

URL fetched before an inbound call is answered to resolve the assistant’s prompt variables. Null when no lookup is configured.

prompt: string
slack: Slack | null
channels: Array<Channel>

The Slack channels the post-call agent may post to. It resolves the channel it was told to use against this list and cannot reach any other.

id: string

The Slack channel ID (e.g. ‘C01234567’).

name?: string | null

Human-readable Slack channel name, cached for display in the UI and given to the LLM when the agent prompt routes by channel name.

connection_id: string

The Nango connection ID linking the org’s Slack workspace to Revox.

start_step_name: string | null
structured_output_config: Array<StructuredOutputConfig> | null

The structured output config to use for the call. This is used to extract the data from the call (like email, name, company name, etc.).

name: string
minLength1
required: boolean
type: "string" | "number" | "boolean" | 3 more
One of the following:
"string"
"number"
"boolean"
"enum"
"date"
"datetime"
description?: string
enum_options?: Array<string>
structured_output_prompt: string | null

Custom prompt for structured data extraction. If not provided, a default prompt is used. Available variables: {{transcript}}, {{call_direction}}, {{user_phone_number}}, {{agent_phone_number}}.

stt_bvc_filter_enabled: boolean

When false, the agent transcribes the raw caller track instead of the BVC noise-cancellation output.

stt_context: SttContext | null

Assistant-level speech-to-text context: structured general key/value pairs plus a list of domain terms. Prompt-derived context is merged in without replacing existing entries.

general: Array<General>
key: string
minLength1
value: string
minLength1
terms: Array<string>
stt_endpoint_latency_level: number | null

Soniox endpoint latency adjustment level (0 to 3). Null: Soniox default.

minimum-9007199254740991
maximum9007199254740991
stt_endpoint_sensitivity: number | null

Soniox endpoint sensitivity (-1 to 1). Null: Soniox default.

stt_model: "stt-rt-v4" | "stt-rt-v5"

Transcriber (speech-to-text) model used for the assistant.

One of the following:
"stt-rt-v4"
"stt-rt-v5"
teams: Teams | null
channels: Array<Channel>

The Teams channels the post-call agent may post to. It resolves the channel it was told to use against this list and cannot reach any other.

id: string

The Microsoft Teams channel ID (e.g. ‘19:561fbdbb…@thread.tacv2’).

team_id: string

The ID of the team the channel belongs to. Needed to post.

name?: string | null

Human-readable channel name, cached for display in the UI and given to the LLM when the agent prompt routes by channel name.

team_name?: string | null

Human-readable team name. Channel names repeat across teams (every team has a ‘General’), so the team name is what tells two of them apart.

connection_id: string

The Nango connection ID linking a Microsoft Teams account to Revox. Messages are posted as that account.

thinking_sound: "city-ambience.ogg" | "forest-ambience.ogg" | "office-ambience.ogg" | 4 more | null

Audio clip to play while the agent is processing a response. One of the built-in LiveKit audio clips; null disables it.

One of the following:
"city-ambience.ogg"
"forest-ambience.ogg"
"office-ambience.ogg"
"crowded-room.ogg"
"keyboard-typing.ogg"
"keyboard-typing2.ogg"
"hold_music.ogg"
thinking_sound_probability: number

Probability [0..1] that the thinking sound plays on any given turn; otherwise the agent is silent while thinking.

minimum0
maximum1
thinking_sound_volume: number

Volume of the thinking sound (0 = silent, 1 = max).

minimum0
maximum1
transfer_destinations: Array<TransferDestination> | null

Where calls can be transferred to when users ask to speak to a human. Null or empty when transfer is not configured.

label: string
minLength1
maxLength60
phone_number: string
type: "standalone" | "multi-step" | "sub-assistant"
One of the following:
"standalone"
"multi-step"
"sub-assistant"
updated_at: unknown
voice: Voice | null
id: string

The ID of the voice.

minLength1
provider: "cartesia" | "elevenlabs" | "gradium"

The provider of the voice.

One of the following:
"cartesia"
"elevenlabs"
"gradium"
model?: "sonic-3" | "sonic-3.5" | "sonic-3.6"

Cartesia TTS model (Cartesia only). Defaults to sonic-3.6 when omitted. Ignored for other providers.

One of the following:
"sonic-3"
"sonic-3.5"
"sonic-3.6"
speed?: number

The speed of the voice. Range depends on provider: Cartesia 0.6–1.5, ElevenLabs 0.7–1.2, Gradium 0.6–1.5. Default is 1.0.

minimum0.6
maximum1.5
volume?: number

Volume of the voice (Cartesia only). 0.5–2.0, default 1.0. Ignored for other providers.

minimum0.5
maximum2
voice_languages: Array<VoiceLanguage> | null

Extra languages for a multilingual assistant, each with its own voice. Calls pick one through their language value, else the phone number’s country; other calls use the assistant’s voice.

language: "en" | "fr" | "es" | 5 more

The language contacts are called in with this voice.

One of the following:
"en"
"fr"
"es"
"de"
"it"
"pt"
"ru"
"zh"
voice: Voice { id, provider, model, 2 more }

The voice used for contacts whose language is this language.

id: string

The ID of the voice.

minLength1
provider: "cartesia" | "elevenlabs" | "gradium"

The provider of the voice.

One of the following:
"cartesia"
"elevenlabs"
"gradium"
model?: "sonic-3" | "sonic-3.5" | "sonic-3.6"

Cartesia TTS model (Cartesia only). Defaults to sonic-3.6 when omitted. Ignored for other providers.

One of the following:
"sonic-3"
"sonic-3.5"
"sonic-3.6"
speed?: number

The speed of the voice. Range depends on provider: Cartesia 0.6–1.5, ElevenLabs 0.7–1.2, Gradium 0.6–1.5. Default is 1.0.

minimum0.6
maximum1.5
volume?: number

Volume of the voice (Cartesia only). 0.5–2.0, default 1.0. Ignored for other providers.

minimum0.5
maximum2
voicemail_message: string | null

If set, when voicemail is detected the agent will speak this message then hang up; if null, hang up immediately.

warm_transfer_summary_instructions: string | null

Warm transfer only: instructions for the supervisor handoff summary; null when not configured or cold transfer.

warm_transfer_voice_speed: number | null

Warm transfer only: voice speed of the briefing to the human colleague; null when it follows voice.speed, not configured, or cold transfer.

minimum0.6
maximum1.5
webhook_url: string | null

The webhook URL to call when the call is completed.

zoho: Zoho | null
connection_id: string

The Nango connection ID linking the org’s Zoho CRM account to Revox.

field_mapping: Array<FieldMapping>

Maps extracted call fields (structured_output / prompt variables) onto Zoho field API names on the upserted record.

source: string

Source key to read from the call: a structured_output field name, falling back to a prompt variable of the same name.

minLength1
zoho_field: string

Destination Zoho field API name on the upserted record (e.g. ‘Email’, ‘Company’, or a custom ‘Budget__c’).

minLength1
log_call_activity: boolean

When true, also log the call as a record in Zoho’s Calls module (related to the upserted prospect via Who_Id).

module: string

Zoho module the prospect record is upserted into (e.g. ‘Leads’ or ‘Contacts’).

minLength1
template?: string | null

Optional Note body template. Supports {{summary}}, {{outcome}}, {{phone}}, {{call_url}}, {{assistant_name}}, {{campaign_name}}, {{transcript}}, plus prompt_variables and structured_output keys. When null/empty a default note (outcome + summary + auto-listed extracted fields) is used.

created_by?: CreatedBy | null

The user who created the assistant.

id: string

The database user id of the creator.

email: string
first_name: string | null
last_name: string | null
is_inbound_receptionist?: boolean
is_realestate_assistant?: boolean

Create an assistant

import Revox from '@revoxai/sdk';

const client = new Revox({
  apiKey: process.env['REVOX_API_KEY'], // This is the default and can be omitted
});

const assistant = await client.assistants.create({ name: 'name', prompt: 'prompt' });

console.log(assistant.assistant);
{
  "assistant": {
    "id": "id",
    "background_sound": "audio/office.ogg",
    "background_sound_volume": 0,
    "cal": {
      "connection_id": "connection_id",
      "event_type_id": "event_type_id"
    },
    "calendly": {
      "connection_id": "connection_id",
      "event_type_id": "event_type_id"
    },
    "call_retry_config": {
      "allowed_days": [
        "monday"
      ],
      "call_twice_in_a_row": true,
      "calling_windows": [
        {
          "calling_window_end_time": "calling_window_end_time",
          "calling_window_start_time": "calling_window_start_time",
          "retry_delay_seconds": {}
        }
      ],
      "max_retry_attempts": 1,
      "timezone": "timezone"
    },
    "cartesia_dictionary_pronunciation_id": "cartesia_dictionary_pronunciation_id",
    "created_at": {},
    "custom_tools": [
      {
        "body_template": "body_template",
        "description": "x",
        "headers": [
          {
            "key": "x",
            "value": "value"
          }
        ],
        "input_schema": [
          {
            "name": "x",
            "required": true,
            "type": "string",
            "description": "description",
            "enum_options": [
              "string"
            ]
          }
        ],
        "method": "GET",
        "name": "name",
        "query_params": [
          {
            "key": "x",
            "value": "value"
          }
        ],
        "url": "x"
      }
    ],
    "end_of_call_sentence": "end_of_call_sentence",
    "first_sentence": "first_sentence",
    "first_sentence_delay_ms": -9007199254740991,
    "first_sentence_mode": "generated",
    "from_phone_number": "from_phone_number",
    "hubspot": {
      "connection_id": "connection_id",
      "meeting_links": [
        {
          "booking_url": "booking_url",
          "duration_ms": 1,
          "is_fallback": true,
          "label": "x",
          "slug": "x"
        }
      ],
      "precall_lookup_enabled": true,
      "post_call_sync": {
        "enabled": true,
        "field_mapping": [
          {
            "hubspot_property": "x",
            "source": "x"
          }
        ]
      }
    },
    "human_transfer_mode": "warm",
    "ivr_navigation_enabled": true,
    "krisp_viva_filter_enabled": true,
    "llm_model": {
      "type": "recommended"
    },
    "logo_url": "logo_url",
    "max_call_duration_secs": 0,
    "max_duration_end_message": "max_duration_end_message",
    "name": "name",
    "organization_id": "organization_id",
    "position": {
      "x": 0,
      "y": 0
    },
    "post_call_prompt": "post_call_prompt",
    "precall_lookup_headers": [
      {
        "key": "key",
        "value": "x"
      }
    ],
    "precall_lookup_url": "precall_lookup_url",
    "prompt": "prompt",
    "slack": {
      "channels": [
        {
          "id": "id",
          "name": "name"
        }
      ],
      "connection_id": "connection_id"
    },
    "start_step_name": "start_step_name",
    "structured_output_config": [
      {
        "name": "x",
        "required": true,
        "type": "string",
        "description": "description",
        "enum_options": [
          "string"
        ]
      }
    ],
    "structured_output_prompt": "structured_output_prompt",
    "stt_bvc_filter_enabled": true,
    "stt_context": {
      "general": [
        {
          "key": "x",
          "value": "x"
        }
      ],
      "terms": [
        "x"
      ]
    },
    "stt_endpoint_latency_level": -9007199254740991,
    "stt_endpoint_sensitivity": 0,
    "stt_model": "stt-rt-v4",
    "teams": {
      "channels": [
        {
          "id": "id",
          "team_id": "team_id",
          "name": "name",
          "team_name": "team_name"
        }
      ],
      "connection_id": "connection_id"
    },
    "thinking_sound": "city-ambience.ogg",
    "thinking_sound_probability": 0,
    "thinking_sound_volume": 0,
    "transfer_destinations": [
      {
        "label": "x",
        "phone_number": "phone_number"
      }
    ],
    "type": "standalone",
    "updated_at": {},
    "voice": {
      "id": "x",
      "provider": "cartesia",
      "model": "sonic-3",
      "speed": 0.6,
      "volume": 0.5
    },
    "voice_languages": [
      {
        "language": "en",
        "voice": {
          "id": "x",
          "provider": "cartesia",
          "model": "sonic-3",
          "speed": 0.6,
          "volume": 0.5
        }
      }
    ],
    "voicemail_message": "voicemail_message",
    "warm_transfer_summary_instructions": "warm_transfer_summary_instructions",
    "warm_transfer_voice_speed": 0.6,
    "webhook_url": "webhook_url",
    "zoho": {
      "connection_id": "connection_id",
      "field_mapping": [
        {
          "source": "x",
          "zoho_field": "x"
        }
      ],
      "log_call_activity": true,
      "module": "x",
      "template": "template"
    },
    "created_by": {
      "id": "id",
      "email": "email",
      "first_name": "first_name",
      "last_name": "last_name"
    },
    "is_inbound_receptionist": true,
    "is_realestate_assistant": true
  }
}
Returns Examples
{
  "assistant": {
    "id": "id",
    "background_sound": "audio/office.ogg",
    "background_sound_volume": 0,
    "cal": {
      "connection_id": "connection_id",
      "event_type_id": "event_type_id"
    },
    "calendly": {
      "connection_id": "connection_id",
      "event_type_id": "event_type_id"
    },
    "call_retry_config": {
      "allowed_days": [
        "monday"
      ],
      "call_twice_in_a_row": true,
      "calling_windows": [
        {
          "calling_window_end_time": "calling_window_end_time",
          "calling_window_start_time": "calling_window_start_time",
          "retry_delay_seconds": {}
        }
      ],
      "max_retry_attempts": 1,
      "timezone": "timezone"
    },
    "cartesia_dictionary_pronunciation_id": "cartesia_dictionary_pronunciation_id",
    "created_at": {},
    "custom_tools": [
      {
        "body_template": "body_template",
        "description": "x",
        "headers": [
          {
            "key": "x",
            "value": "value"
          }
        ],
        "input_schema": [
          {
            "name": "x",
            "required": true,
            "type": "string",
            "description": "description",
            "enum_options": [
              "string"
            ]
          }
        ],
        "method": "GET",
        "name": "name",
        "query_params": [
          {
            "key": "x",
            "value": "value"
          }
        ],
        "url": "x"
      }
    ],
    "end_of_call_sentence": "end_of_call_sentence",
    "first_sentence": "first_sentence",
    "first_sentence_delay_ms": -9007199254740991,
    "first_sentence_mode": "generated",
    "from_phone_number": "from_phone_number",
    "hubspot": {
      "connection_id": "connection_id",
      "meeting_links": [
        {
          "booking_url": "booking_url",
          "duration_ms": 1,
          "is_fallback": true,
          "label": "x",
          "slug": "x"
        }
      ],
      "precall_lookup_enabled": true,
      "post_call_sync": {
        "enabled": true,
        "field_mapping": [
          {
            "hubspot_property": "x",
            "source": "x"
          }
        ]
      }
    },
    "human_transfer_mode": "warm",
    "ivr_navigation_enabled": true,
    "krisp_viva_filter_enabled": true,
    "llm_model": {
      "type": "recommended"
    },
    "logo_url": "logo_url",
    "max_call_duration_secs": 0,
    "max_duration_end_message": "max_duration_end_message",
    "name": "name",
    "organization_id": "organization_id",
    "position": {
      "x": 0,
      "y": 0
    },
    "post_call_prompt": "post_call_prompt",
    "precall_lookup_headers": [
      {
        "key": "key",
        "value": "x"
      }
    ],
    "precall_lookup_url": "precall_lookup_url",
    "prompt": "prompt",
    "slack": {
      "channels": [
        {
          "id": "id",
          "name": "name"
        }
      ],
      "connection_id": "connection_id"
    },
    "start_step_name": "start_step_name",
    "structured_output_config": [
      {
        "name": "x",
        "required": true,
        "type": "string",
        "description": "description",
        "enum_options": [
          "string"
        ]
      }
    ],
    "structured_output_prompt": "structured_output_prompt",
    "stt_bvc_filter_enabled": true,
    "stt_context": {
      "general": [
        {
          "key": "x",
          "value": "x"
        }
      ],
      "terms": [
        "x"
      ]
    },
    "stt_endpoint_latency_level": -9007199254740991,
    "stt_endpoint_sensitivity": 0,
    "stt_model": "stt-rt-v4",
    "teams": {
      "channels": [
        {
          "id": "id",
          "team_id": "team_id",
          "name": "name",
          "team_name": "team_name"
        }
      ],
      "connection_id": "connection_id"
    },
    "thinking_sound": "city-ambience.ogg",
    "thinking_sound_probability": 0,
    "thinking_sound_volume": 0,
    "transfer_destinations": [
      {
        "label": "x",
        "phone_number": "phone_number"
      }
    ],
    "type": "standalone",
    "updated_at": {},
    "voice": {
      "id": "x",
      "provider": "cartesia",
      "model": "sonic-3",
      "speed": 0.6,
      "volume": 0.5
    },
    "voice_languages": [
      {
        "language": "en",
        "voice": {
          "id": "x",
          "provider": "cartesia",
          "model": "sonic-3",
          "speed": 0.6,
          "volume": 0.5
        }
      }
    ],
    "voicemail_message": "voicemail_message",
    "warm_transfer_summary_instructions": "warm_transfer_summary_instructions",
    "warm_transfer_voice_speed": 0.6,
    "webhook_url": "webhook_url",
    "zoho": {
      "connection_id": "connection_id",
      "field_mapping": [
        {
          "source": "x",
          "zoho_field": "x"
        }
      ],
      "log_call_activity": true,
      "module": "x",
      "template": "template"
    },
    "created_by": {
      "id": "id",
      "email": "email",
      "first_name": "first_name",
      "last_name": "last_name"
    },
    "is_inbound_receptionist": true,
    "is_realestate_assistant": true
  }
}