Skip to main content
PATCH
Update an assistant

Authorizations

Authorization
string
header
required

API key (fam_..., created under Settings → API Keys) or an OAuth 2.0 access token (fam_at_...). Keys can be restricted to scopes such as assistants:read, calls:write, campaigns:write, automations:read, dashboards:read, dashboards:write, leads:write, segments:write, phone_numbers:write, sip_trunks:write, knowledge:write, voices:read, billing:read, settings:write, platform:read, platform:write; a *:write scope implies the matching *:read. Automation and dashboard endpoints also accept the legacy calls:* scope. Keys without scope restrictions have full access.

Path Parameters

id
string<uuid>
required

Assistant ID.

Body

application/json

Writable assistant fields. Unknown fields are ignored. Non-null engine model overrides require the Fallbacks & Guardrails add-on and are validated against the assistant owner's effective catalog access and engine compatibility. Null resets to the next default level.

name
string
is_active
boolean
revision
integer

Monotone optimistic concurrency revision.

Required range: x >= 1
usage_count
integer

Number of assistants currently assigned to this tool.

Required range: x >= 0
system_prompt
string
mode
enum<string>
Available options:
pipeline,
realtime,
half_cascade
realtime_provider
string | null
realtime_model
string | null
realtime_voice
string | null
llm_provider
enum<string> | null
Available options:
openai,
azure,
google,
groq,
anthropic,
null
llm_model
string | null
half_cascade_provider
string | null
half_cascade_model
string | null
llm_temperature
number
stt_provider
enum<string>
Available options:
deepgram,
openai,
google,
azure
stt_model
string
stt_language
string
tts_provider
enum<string>
Available options:
cartesia,
elevenlabs,
openai,
google,
azure
tts_model
string | null
tts_voice
string | null
tts_speed
number
tts_emotion
string[]

Cartesia dynamic-emotions toggle. Send [] to disable it or any non-empty array to enable every supported Cartesia emotion.

tts_style_prompt
string | null

Optional free-text speaking-style instructions for compatible TTS models. Send null to clear the override.

elevenlabs_stability
number | null

Voice stability override. Send null to use the voice-provider default.

Required range: 0 <= x <= 1
elevenlabs_similarity
number | null

Voice similarity override. Send null to use the voice-provider default.

Required range: 0 <= x <= 1
elevenlabs_style
number | null

Voice-style exaggeration override. Send null to use the voice-provider default.

Required range: 0 <= x <= 1
elevenlabs_speaker_boost
boolean | null

Speaker-boost override. Send null to use the voice-provider default.

turn_detection
enum<string>
Available options:
multilingual_model,
english_model,
vad,
stt
vad_min_silence_ms
integer
allow_interruptions
boolean
min_interruption_duration_ms
integer
noise_cancellation
enum<string>
Available options:
bvc,
bvc_telephony,
none
preemptive_generation
boolean
max_tool_steps
integer
first_message
string | null
greeting_mode
enum<string>
Available options:
agent_speaks_first,
user_speaks_first
greeting_allow_interruptions
boolean

When true, the caller may barge in during the opening greeting (first message / audio / silence fallback). Default false = play greeting uninterrupted. Separate from allow_interruptions (rest of the call).

ai_speaks_after_silence
boolean

When greeting_mode is user_speaks_first: after ai_entry_timeout_sec of initial silence, the assistant speaks (static or dynamic). Default false.

silence_greeting_mode
enum<string>
Available options:
static,
dynamic
silence_greeting_message
string
ai_entry_timeout_sec
integer
Required range: 1 <= x <= 20
pre_call
object

iOS/Android Call Screen Handling. Mirrored into flow_json.pre_call when a flow exists.

flow_json
object | null

Agent type. Omit or null = Single prompt (default). Object = Conversational flow (Flow JSON v1). Seed Start→Agent→End for a basic flow; non-trivial graphs may require the flow_builder plan toggle. In flow mode, system_prompt is the Advanced / base prompt (agent-node text is appended).

recording_enabled
boolean
max_call_duration_sec
integer | null

Maximum call duration in seconds (60–1800). null = unlimited (budget cap still applies).

Required range: 60 <= x <= 1800
inbound_ringing_timeout_sec
integer

How long inbound callers hear ringing before the call times out (30–120 s, default 60).

Required range: 30 <= x <= 120
outbound_ringing_timeout_sec
integer

How long outbound SIP/WhatsApp calls ring before no-answer (15–80 s, default 45).

Required range: 15 <= x <= 80
idle_timeout_sec
integer
transcription_timeout_sec
number | null

Seconds after VAD detects speech with no STT transcript before asking the caller to repeat. null disables.

Required range: 1 <= x <= 30
knowledgebase_id
string<uuid> | null
knowledge_gap_mode
enum<string>
Available options:
off,
questions_only,
draft_for_review,
tentative_live
webhook_url
string | null

Agent-level post-call webhook URL.

webhook_timeout_sec
integer
Required range: 1 <= x <= 30
webhook_retries
integer
Required range: 0 <= x <= 5
metadata
object
background_audio
object

BackgroundAudioPlayer config (ambient, ambient_volume, thinking, thinking_volume). {} = off. Hold music is configured on the warm-transfer tool, not here.

adaptive_interruptions
boolean
realtime_turn_mode
enum<string>

Realtime turn handling: robust voice activity, semantic completion, or adaptive barge-in.

Available options:
server_vad,
semantic,
adaptive
realtime_eagerness
enum<string>

How quickly the assistant responds when realtime_turn_mode is semantic.

Available options:
auto,
low,
medium,
high
idle_messages
string[]
idle_max_rounds
integer
fallback_config
object
pronunciation_map
object
tts_filter_markdown
boolean
tts_filter_emoji
boolean
guardrails
object
language_voices
object

Per-language voice overrides for Pipeline/Half-cascade. Languages without an entry keep the main voice.

auto_language_switch
boolean

Automatic response-language switching; derived from secondary_languages by the dashboard.

output_volume
number
speaking_rate
number
text_only_enabled
boolean
memory_enabled
boolean
memory_mode
enum<string>

inherit follows the workspace memory default; on/off override it.

Available options:
inherit,
on,
off
memory_scope
enum<string>

workspace = shared across assistants; assistant = private to this assistant; both = shared identity + per-assistant history.

Available options:
workspace,
assistant,
both
memory_read_channels
enum<string>[]

Per-assistant read allowlist intersected with workspace policy. Send [] to disable reads.

A currently operational memory channel. Web is deliberately excluded until signed-in browser users have a server-verified identity boundary.

Available options:
voice,
sms,
whatsapp,
email,
telegram,
slack,
messenger,
teams,
discord,
gchat,
x
memory_write_channels
enum<string>[]

Per-assistant write allowlist intersected with workspace policy. Send [] to disable writes.

A currently operational memory channel. Web is deliberately excluded until signed-in browser users have a server-verified identity boundary.

Available options:
voice,
sms,
whatsapp,
email,
telegram,
slack,
messenger,
teams,
discord,
gchat,
x
memory_categories
enum<string>[]

Allowed summary categories. Send [] for metadata-only memory with no new content summary.

Available options:
identity,
preferences,
agreements,
open_items
redact_pii
boolean

When true, apply pii_redaction entity filters to stored transcripts.

pii_redaction
object

PII entity categories + optional custom regexes.

analysis_config
object

Post-call analysis configuration. When set (non-empty), the LLM judge evaluates each finished transcript and writes the result to calls.analysis (plus the denormalized calls.sentiment/calls.success filter columns). All fields are optional.

qa_scorecard_config
object | null

AI-QA scorecard configuration (plan-gated ai_qa_scorecards). null or enabled: false disables scoring.

timezone
string

IANA timezone of the assistant (e.g. Europe/Berlin, default). Anchors the get_current_time system tool, the {{time}}/{{date}}/{{datetime}}/{{weekday}} system variables, and the check_business_hours built-in tool. On campaign calls the campaign's timezone overrides it per call.

primary_language
string

Language the assistant answers in by default (ISO-639-1, see GET /languages).

secondary_languages
string[]

Languages the assistant may switch to when the caller clearly speaks them (ISO-639-1). Non-empty implies multilingual STT + auto language switch.

variables
object[]

Custom variable definitions, referenced as {{key}} and resolved per call (explicit call values > inbound webhook enrichment > system variables > default_value).

variable_webhook_url
string | null

Optional webhook called on inbound calls to enrich variable values before the conversation starts.

builtin_tools
object[]

Built-in tool configurations (also accepted as tools for compatibility).

Response

The updated assistant.

data
object
required

A voice assistant configuration. Nullable model overrides are independent per engine: pipeline uses llm_*, realtime uses realtime_*, and half-cascade uses half_cascade_* for its text-capable realtime input plus tts_* for output.