Agents

Update Agent

Change any subset of an agent's settings. Fields left out of the body keep their current value; to clear a field, send its empty value explicitly where the field allows it.

patch/api/v1/agents/{agent_id}

Request

  • Base URL: https://api.dialogbrain.com (the document declares no server; this is the origin it was published from)
  • URL: https://api.dialogbrain.com/api/v1/agents/{agent_id}
  • Auth: none declared

Path parameters

agent_idinteger required

Request body

namestring nullable

New name for the agent

descriptionstring nullable

New description for the agent

prompt_idinteger nullable

Prompt ID to assign (null to detach)

send_mode'auto' | 'draft' nullable

Default send mode: 'auto' or 'draft'. OMIT to leave the send-mode unchanged.

status'active' | 'paused' | 'archived' nullable

Agent status: 'active', 'paused', or 'archived'. OMIT to leave the status unchanged.

text_engine'rule_based' | 'agentic' | 'claude_channels' | 'external_agent' nullable

Text-execution engine: 'agentic', 'ai_assisted', 'rule_based', or 'claude_channels'. Replaces the legacy execution_mode field (20260523_002). Voice is now derived from triggers, not engine. OMIT to leave unchanged.

remote_toolstring nullable

For an external_agent: the integration tool that starts the remote agent.

model'claude-haiku-4-5-20251001' | 'claude-opus-4-6' | 'claude-sonnet-4-6' | 'claude-sonnet-5' | 'dashscope-glm-5.2' | 'dashscope-glm-5.2-nothink' | 'deepseek-v4-flash' | 'deepseek-v4-flash-nothink' | 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano' | 'gpt-4o' | 'kimi-k2.6' | 'qwen-flash' | 'qwen-plus' | 'qwen3-vl-plus' | 'qwen3.6-flash' | 'qwen3.6-plus' nullable

The model the agent runs on; omit for the platform default.

max_iterationsinteger nullable

Hard cap on loop turns per run; omit to leave it unchanged.

api_surface'chat_completions' | 'responses' nullable

OpenAI endpoint routing setting.

native_web_searchboolean nullable

Whether the agent may use the model provider's built-in web search.

prompt_textstring nullable

The agent's system prompt.

auto_reply_rulesstring nullable

Plain-English rules injected into the fast model's prompt.

priorityinteger nullable

Agent priority for trigger matching. LOWER number = HIGHER priority (wins tiebreaks). Typical range 1-100. Fallback auto-reply agents use 10; specialised/topical agents use 100. When two agents match the same incoming message, the one with the lower priority number fires.

vision_enabledboolean nullable

Per-agent opt-in for vision content.

include_situationboolean nullable

Include situation context (channel, sender info, trigger type) in the agent's prompt. OMIT to leave this flag unchanged.

include_learned_styleboolean nullable

Include learned communication style (per-contact tone, dormancy state) in the agent's prompt. OMIT to leave this flag unchanged.

include_job_stateboolean nullable

Include current job state (active job context, tasks, notes) in the agent's prompt. OMIT to leave this flag unchanged.

include_conversation_historyboolean nullable

Include recent messages from this thread (up to 20) in the agent's prompt. A voice call follows it too: true (default) starts the call with the earlier messages and calls with this caller, false starts every call from zero (for an agent that takes a new order each call). OMIT to leave this flag unchanged.

include_thread_summaryboolean nullable

Include condensed summary of older thread messages in the agent's prompt. OMIT to leave this flag unchanged.

include_tool_call_historyboolean nullable

Include the agent's own past calls and results from recent runs.

include_safety_guidelinesboolean nullable

Inject the generic Safety Guidelines block (~80 tokens) into the system prompt. Default OFF — enable only if you don't already write safety rules in your Instructions. Agentic mode only. OMIT to leave this flag unchanged.

include_data_confidentialityboolean nullable

Inject the Data Confidentiality block (~250 tokens, cross-contact PII isolation + prompt-injection defense) into the system prompt. Default OFF. Agentic mode only. OMIT to leave this flag unchanged.

include_factual_accuracyboolean nullable

Inject the Factual Accuracy block (~100 tokens, generic anti-hallucination rules) into the system prompt. Default OFF — skip if you write domain-specific accuracy rules in Instructions. Agentic mode only. OMIT to leave this flag unchanged.

include_specialistsboolean nullable

Inject a [SPECIALISTS] block (~50–200 tokens) listing the workspace's delegation-capable agents so a router-style agent can pick a handoff target without first calling agents.list. Default OFF for new agents; the Router template ships with this ON. Agentic mode only. OMIT to leave this flag unchanged.

fast_modelstring nullable

Model for the fast-path responder (voice, text auto-reply, agent executor). Defaults to deepseek-v4-flash-nothink when unset. Non-Anthropic models (deepseek-v4-flash-nothink, gpt-4.1-nano, kimi-k2.6) do NOT use BYOK today — they use the system API key + credits. Pass null to revert to default.

fast_prompt_overridestring nullable

Full fast-path prompt override; placeholders are substituted.

scriptstring nullable

rule_based Python code run in the workbench sandbox on each matched event.

voice_primary_modelstring nullable

Primary model for voice turns.

voice_realtime_model'gpt-realtime' | 'gpt-realtime-mini' | 'gemini-3.8-live' | 'gemini-3.1-flash-live-preview' | 'gemini-2.5-flash-native-audio-latest' | 'gemini-2.5-flash-native-audio-preview-12-2025' | 'default' nullable

Realtime (v2v) model for the agent's voice_engine. openai_realtime: 'gpt-realtime' (~18c/min on short calls) or 'gpt-realtime-mini' (~75% cheaper). gemini_realtime: a Gemini Live model, newest first 'gemini-3.8-live' (the default), 'gemini-3.1-flash-live-preview', 'gemini-2.5-flash-native-audio-latest', 'gemini-2.5-flash-native-audio-preview-12-2025'. 'default' = back to the engine's default. OMIT to leave unchanged.

voice_realtime_voice'Puck' | 'Charon' | 'Fenrir' | 'Orus' | 'Kore' | 'Aoede' | 'Leda' | 'Zephyr' | 'default' nullable

The voice a realtime (v2v) engine speaks in. gemini_realtime: Puck (male, upbeat), Charon (male, informative), Fenrir (male, excitable), Orus (male, firm), Kore (female, firm), Aoede (female, breezy), Leda (female, youthful), Zephyr (female, bright); default Puck. An engine not named here has a fixed voice. Separate from voice_tts_voice, which is the pipeline engine's TTS voice. 'default' = back to the engine's default. OMIT to leave unchanged.

voice_endpointing_max_delaynumber nullable

LiveKit endpointing.max_delay (0.5-10.0s, default 3.0). Ceiling on how long the agent waits for a turn to end. voice_endpointing_min_delay is the floor after silence; this is what stops a thinking pause from holding the turn open, and it is the knob to raise when an agent talks over someone who pauses mid-thought.

voice_endpointing_mode'fixed' | 'dynamic' nullable

LiveKit endpointing mode. 'fixed' (default) waits voice_endpointing_min_delay every turn; 'dynamic' adapts the wait from the conversation's own rhythm. OMIT to leave unchanged.

voice_max_call_duration_sinteger nullable

Wall-clock cap for a voice call in seconds, clamped to 60-14400; the worker ends the call at it regardless of what the conversation is doing. OMIT to leave unchanged (default is no cap — a call ends when the conversation ends). To REMOVE an existing cap, clear the field in the agent's Voice settings UI (0 there = no limit). Two agents talking to each other are capped separately by calls.agent_duel's own max_duration_s.

voice_output_gain_dbnumber nullable

Output attenuation in dB applied to the agent's WhatsApp call audio before the codec (-12.0 to 0.0, default 0 = unchanged). Use a negative value (e.g. -3.5) when a hot voice engine (OpenAI Realtime rides near 0 dBFS) causes blown-speaker distortion on loud words: the 24 kbps call codec needs headroom, and this restores it. Applied on the next call, no deploy needed.

voice_max_tokensinteger nullable

Max tokens per voice reply.

voice_max_tool_callsinteger nullable

Maximum calls per voice turn.

voice_stt_provider'deepgram' | 'gladia' nullable

Speech-to-text provider. 'deepgram' (default) runs Nova-3 / Flux and preserves existing behaviour. 'gladia' routes to Gladia streaming STT (solaria-1), which is Deepgram-class latency and covers ~115 languages Deepgram does NOT — including Uzbek ('uz'), Kazakh ('kk'), Azerbaijani ('az'), Tajik ('tg'). Pick 'gladia' when the caller's language is outside Deepgram's coverage, then set voice_stt_language to that language's code. The provider also decides which language codes voice_stt_language accepts. OMIT to leave the STT provider unchanged.

voice_stt_model'flux' | 'flux-general-en' | 'flux-general-multi' | 'nova-3' nullable

Speech-to-text model for voice.

voice_stt_language'af' | 'am' | 'ar' | 'ar-AE' | 'ar-DZ' | 'ar-EG' | 'ar-IQ' | 'ar-IR' | 'ar-JO' | 'ar-KW' | 'ar-LB' | 'ar-MA' | 'ar-PS' | 'ar-QA' | 'ar-SA' | 'ar-SD' | 'ar-SY' | 'ar-TD' | 'ar-TN' | 'as' | 'ast' | 'az' | 'ba' | 'be' | 'bg' | 'bn' | 'bo' | 'br' | 'bs' | 'ca' | 'ceb' | 'cs' | 'cy' | 'da' | 'da-DK' | 'de' | 'de-CH' | 'el' | 'en' | 'en-AU' | 'en-GB' | 'en-IN' | 'en-NZ' | 'en-US' | 'es' | 'es-419' | 'et' | 'eu' | 'fa' | 'ff' | 'fi' | 'fo' | 'fr' | 'fr-CA' | 'fy' | 'ga' | 'gd' | 'gl' | 'gu' | 'ha' | 'haw' | 'he' | 'hi' | 'hr' | 'ht' | 'hu' | 'hy' | 'id' | 'ig' | 'ilo' | 'is' | 'it' | 'ja' | 'jv' | 'ka' | 'kk' | 'km' | 'kn' | 'ko' | 'ko-KR' | 'la' | 'lb' | 'lg' | 'ln' | 'lo' | 'lt' | 'lv' | 'mg' | 'mi' | 'mk' | 'ml' | 'mn' | 'mo' | 'mr' | 'ms' | 'mt' | 'multi' | 'my' | 'ne' | 'nl' | 'nl-BE' | 'nn' | 'no' | 'oc' | 'or' | 'pa' | 'pl' | 'ps' | 'pt' | 'pt-BR' | 'pt-PT' | 'ro' | 'ru' | 'sa' | 'sd' | 'si' | 'sk' | 'sl' | 'sn' | 'so' | 'sq' | 'sr' | 'ss' | 'su' | 'sv' | 'sv-SE' | 'sw' | 'ta' | 'te' | 'tg' | 'th' | 'th-TH' | 'tk' | 'tl' | 'tn' | 'tr' | 'tt' | 'uk' | 'ur' | 'uz' | 'vi' | 'wo' | 'xh' | 'yi' | 'yo' | 'zh' | 'zh-CN' | 'zh-HK' | 'zh-Hans' | 'zh-Hant' | 'zh-TW' | 'zu' nullable

STT language code, validated against the SELECTED voice_stt_provider. 'multi' (default) enables autodetect / code-switching on either provider; a singleton like 'en', 'ru', 'uz' gives higher accuracy when the caller language is known. Deepgram provider: 'en' runs on Flux (fastest, eager end-of-turn); 'multi' and every other language run on Nova-3. Some languages — notably Thai ('th'), Vietnamese ('vi'), Indonesian ('id'), Tagalog ('tl') — are NOT in Nova-3's 'multi' auto-detect set, so those callers MUST be given an explicit code. Gladia provider: use its codes (e.g. 'uz' Uzbek, 'kk' Kazakh, 'az' Azerbaijani, 'tg' Tajik) — these are NOT valid under Deepgram. The enum below lists the union of both providers' codes; a code invalid for the chosen provider is rejected on save. OMIT to leave the STT language unchanged.

voice_tts_provider'alibaba' | 'cartesia' | 'deepgram' | 'openai' | 'qwen' | 'xai' nullable

Text-to-speech provider: 'deepgram' (default, Aura-2 EN-only), 'openai' (multilingual), 'cartesia' (Sonic-3, ultra-low TTFB, multilingual), 'alibaba' (CosyVoice v3-flash, multilingual, ~95ms TTFB), 'qwen' (Qwen3-TTS, self-hosted), or 'xai' (Grok, ~20 langs). OMIT to leave the TTS provider unchanged.

voice_tts_voicestring nullable

TTS voice id — provider-specific (e.g. 'aura-2-thalia-en' for Deepgram, 'alloy' for OpenAI, Cartesia voice UUID). Pass null to revert to provider default.

voice_tts_languagestring nullable

TTS language code, BCP-47 lite e.g. 'en', 'es', 'pt-BR' (Cartesia only, default 'en').

voice_tts_speednumber nullable

TTS playback speed multiplier (0.5-2.0, default 1.0). OpenAI/Cartesia only — ignored for Deepgram.

voice_endpointing_min_delaynumber nullable

Silence after end-of-utterance before agent replies (0.1-2.0s, default 0.3). Higher = fewer false interrupts; lower = snappier.

voice_interruption_min_durationnumber nullable

Min caller speech duration to interrupt the agent (0.1-1.5s, default 0.25). Higher = ignore short fillers like 'uh-huh'.

voice_group_interim_barge_inboolean nullable

GROUP/Meet barge-in: interrupt the agent AS SOON AS a participant starts speaking (on the interim transcript), instead of waiting for the finished utterance. Default true. Set true to make a presenter/group agent easy to interrupt mid-sentence (word-gated by voice_group_barge_in_min_words so ambient noise can't trip it); false = only a completed utterance interrupts. OMIT to leave unchanged.

voice_group_barge_in_min_wordsinteger nullable

GROUP/Meet barge-in word gate (1-6, default 1): a participant line must have at least this many words to interrupt the agent. 1 = any word interrupts (most responsive); raise to ignore short cross-talk. OMIT to leave unchanged.

voice_group_barge_in_requires_addressboolean nullable

GROUP/Meet barge-in: when true, only lines that ADDRESS the agent (by name/keyword) interrupt it — two humans talking to each other won't break the walk. Default false. OMIT to leave unchanged.

voice_greetingstring nullable

Opening line the agent speaks when the call connects. Pass an empty string "" to clear. Omit or null leaves unchanged.

voice_greeting_returningstring nullable

Greeting variant for RETURNING callers (thread has prior history or a resolved name). Supports '{name}' — replaced with the caller's name when known, stripped when not. Pass an empty string "" to clear (always use voice_greeting). Omit or null leaves unchanged.

voice_filler_enabledboolean nullable

Emit thinking filler audio while working.

voice_denoiseboolean nullable

Server-side noise suppression (DeepFilterNet) on the INBOUND caller audio before STT — cleans background noise so the agent hears callers in loud/public places and gets fewer false barge-ins. Channel-agnostic: applies to every voice channel the agent answers on. Default false (unset). OMIT to leave unchanged.

voice_filler_audio_presetstring nullable

Which bundled clip plays as thinking filler.

voice_greeting_interruptibleboolean nullable

Allow the caller to barge in during the opener TTS. Default true (trial-friendly — long greetings can be interrupted). Set false on outbound-call agents whose configured opener would otherwise get preempted by the caller's 'Hello?' triggering an off-script auto-turn. OMIT to leave this flag unchanged.

voice_silence_reprompt_snumber nullable

Re-prompt a silent caller after N seconds.

voice_greeting_prerenderboolean nullable

Pre-synthesize the greeting in the agent's voice.

voice_speak_firstboolean nullable

Greet immediately, or listen first and answer.

voice_preemptive_generationboolean nullable

Speculatively start the model on speech-to-text partials.

voice_hold_ready_replyboolean nullable

Keep a ready reply the caller talked over and say it at the next pause.

voice_record_callsboolean nullable

Record voice calls handled by this agent (stereo audio: caller and agent on separate channels), stored with the call for later playback. Default false. Ensure callers are informed of recording where consent rules apply. OMIT to leave this flag unchanged.

voice_record_announceboolean nullable

On recorded calls, prepend a short 'this call may be recorded' notice to the agent's greeting. Only takes effect when voice_record_calls is enabled. Default false. OMIT to leave unchanged.

voice_call_analysisboolean nullable

Run post-call analysis after each answered call.

voice_turn_detector'vad' | 'multilingual' nullable

Voice end-of-turn detector: 'vad' (default — sharp, low-latency) or 'multilingual' (semantic model, ~1s slower per turn, fewer mid-pause cuts). OMIT to leave unchanged.

voice_engine'pipeline' | 'openai_realtime' | 'gemini_realtime' nullable

Voice execution engine.

voice_v2v_transcriptsboolean nullable

Enable live transcripts for voice-to-voice engines (default true). OMIT to leave unchanged.

pause_on_human_replyboolean nullable

Pause the agent on a thread the moment a human operator replies there. Default true. OMIT to leave unchanged.

resume_policystring nullable

When a human-paused thread hands control back to the agent: 'manual' (stays paused until an operator resumes it from the thread header), 'next_incoming_from_guest' (default — resumes on the contact's very next message), or 'after_<N>_hours' (e.g. 'after_2_hours'). With 'next_incoming_from_guest' a manual takeover lasts exactly one message; pick 'manual' when a person is expected to finish the conversation. OMIT to leave unchanged.

debounce_secondsinteger nullable

Seconds to wait after the last inbound message before generating, so rapid-fire messages coalesce into one reply (0-120, default 5). OMIT to leave unchanged.

voice_flux_eot_thresholdnumber nullable

Flux STT end-of-turn confidence threshold (0.1-1.0). Higher = wait for more certainty before finalizing the turn. Flux STT only (ignored on nova-3). OMIT to keep the worker default (0.7).

voice_flux_eager_eot_thresholdnumber nullable

Flux eager end-of-turn threshold.

voice_flux_eot_timeout_msinteger nullable

Flux end-of-turn hard timeout in ms (500-15000). Flux STT only. OMIT to keep the worker default (5000).

voice_early_finalize_confidencenumber nullable

Flux early-finalize confidence (0.1-1.0, worker default 0.65). Lower = finalize sooner on trailing silence (snappier, small mid-word clip risk). Flux STT only. OMIT to leave unchanged.

voice_mip_opt_outboolean nullable

Opt out of Deepgram's model-improvement program (privacy) for Flux STT. Default false. OMIT to leave unchanged.

default_calendar_idstring nullable

Default Google calendar for this agent's calendar operations.

Response

Successful Response

unknown required

Changes

No recorded changes to this operation across all 5 revisions of this API.