Skip to content
RevoxRevox
Get started
API Reference
Assistants

Update an assistant

assistants.update(id, **kwargs) -> AssistantUpdateResponse { assistant, unpatched_calls_notice }
PATCH/assistants/{id}

Update one or more fields on an existing assistant. Supports partial updates — only the fields you include in the request body will be changed. You can update the prompt, voice, first sentence, name, or any other assistant property without affecting the rest of the configuration.

ParametersExpand Collapse
id: String
background_sound: :"audio/office.ogg"

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

background_sound_volume: Float

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

minimum0
maximum1
cal: Cal{ connection_id, event_type_id}
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{ connection_id, event_type_id}
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{ allowed_days, call_twice_in_a_row, calling_windows, 2 more}

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: bool

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, calling_window_start_time, retry_delay_seconds}]
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: untyped

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: Integer

Maximum number of call retry attempts. Default: 3.

exclusiveMinimum0
maximum9007199254740991
timezone: String

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

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

minLength1
custom_tools: Array[CustomTool{ body_template, description, headers, 5 more}]

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

body_template: String

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{ key, value}]

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

key: String
minLength1
value: String
input_schema: Array[InputSchema{ name, required, type, 2 more}]

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

name: String
minLength1
required: bool
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{ key, value}]

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: Integer

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

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{ connection_id, meeting_links, precall_lookup_enabled, post_call_sync}

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: bool

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: bool

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{ hubspot_property, source}]

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

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: bool

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

krisp_viva_filter_enabled: bool

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:
class 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.

class 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"
class 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.

class 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).

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

class 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
class 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

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: Float

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

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
name: String
position: Position{ x, y_}

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

x: Float
y_: Float
post_call_prompt: String

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{ key, value}]

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

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
prompt: String

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

slack: Slack{ channels, connection_id}

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{ id, name}]

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

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

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

maxLength255
structured_output_config: Array[StructuredOutputConfig{ name, required, type, 2 more}]

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: bool
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

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: bool

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

stt_context: SttContext{ general, terms}

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, value}]
key: String
minLength1
value: String
minLength1
terms: Array[String]
stt_endpoint_latency_level: Integer

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: Float

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{ channels, connection_id}

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{ id, team_id, name, team_name}]

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

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

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

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: Float

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

minimum0
maximum1
thinking_sound_volume: Float

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

minimum0
maximum1
transfer_destinations: Array[TransferDestination{ label, phone_number}]

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{ id, provider, model, 2 more}

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: Float

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: Float

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

minimum0.5
maximum2
voice_languages: Array[VoiceLanguage{ language, voice}]

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: Float

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: Float

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

minimum0.5
maximum2
voicemail_message: String

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

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: Float

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{ connection_id, field_mapping, log_call_activity, 2 more}

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{ source, zoho_field}]

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: bool

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

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
class AssistantUpdateResponse { assistant, unpatched_calls_notice }
assistant: Assistant{ id, background_sound, background_sound_volume, 52 more}
id: String
background_sound: :"audio/office.ogg"

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

background_sound_volume: Float

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

minimum0
maximum1
cal: Cal{ connection_id, event_type_id}
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{ connection_id, event_type_id}
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{ allowed_days, call_twice_in_a_row, calling_windows, 2 more}

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: bool

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, calling_window_start_time, retry_delay_seconds}]
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: untyped

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: Integer

Maximum number of call retry attempts. Default: 3.

exclusiveMinimum0
maximum9007199254740991
timezone: String

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

Optional Cartesia pronunciation dictionary ID linked to this assistant.

created_at: untyped
custom_tools: Array[CustomTool{ body_template, description, headers, 5 more}]
body_template: String

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{ key, value}]

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

key: String
minLength1
value: String
input_schema: Array[InputSchema{ name, required, type, 2 more}]

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

name: String
minLength1
required: bool
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{ key, value}]

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
first_sentence: String
first_sentence_delay_ms: Integer

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

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

hubspot: Hubspot{ connection_id, meeting_links, precall_lookup_enabled, post_call_sync}
connection_id: String

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

precall_lookup_enabled: bool

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: bool

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{ hubspot_property, source}]

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

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: bool

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

krisp_viva_filter_enabled: bool

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:
class 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.

class 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"
class 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.

class 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).

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

class 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
class 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

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

max_call_duration_secs: Float

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

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{ x, y_}
x: Float
y_: Float
post_call_prompt: String
precall_lookup_headers: Array[PrecallLookupHeader{ key, value}]

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

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{ channels, connection_id}
channels: Array[Channel{ id, name}]

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

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
structured_output_config: Array[StructuredOutputConfig{ name, required, type, 2 more}]

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: bool
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

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: bool

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

stt_context: SttContext{ general, terms}

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, value}]
key: String
minLength1
value: String
minLength1
terms: Array[String]
stt_endpoint_latency_level: Integer

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

minimum-9007199254740991
maximum9007199254740991
stt_endpoint_sensitivity: Float

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{ channels, connection_id}
channels: Array[Channel{ id, team_id, name, team_name}]

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

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

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

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: Float

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

minimum0
maximum1
thinking_sound_volume: Float

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

minimum0
maximum1
transfer_destinations: Array[TransferDestination{ label, phone_number}]

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: untyped
voice: Voice{ id, provider, model, 2 more}
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: Float

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: Float

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

minimum0.5
maximum2
voice_languages: Array[VoiceLanguage{ language, voice}]

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: Float

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: Float

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

minimum0.5
maximum2
voicemail_message: String

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

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

warm_transfer_voice_speed: Float

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

The webhook URL to call when the call is completed.

zoho: Zoho{ connection_id, field_mapping, log_call_activity, 2 more}
connection_id: String

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

field_mapping: Array[FieldMapping{ source, zoho_field}]

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: bool

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

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{ id, email, first_name, last_name}

The user who created the assistant.

id: String

The database user id of the creator.

email: String
first_name: String
last_name: String
is_inbound_receptionist: bool
is_realestate_assistant: bool
unpatched_calls_notice: UnpatchedCallsNotice{ count, variables}
count: Float
variables: Array[String]

Update an assistant

require "revox"

revox = Revox::Client.new(api_key: "My API Key")

assistant = revox.assistants.update("id")

puts(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
  },
  "unpatchedCallsNotice": {
    "count": 0,
    "variables": [
      "string"
    ]
  }
}
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
  },
  "unpatchedCallsNotice": {
    "count": 0,
    "variables": [
      "string"
    ]
  }
}