Configuration

Configuration is the Builder’s home tab: define how your agent behaves, how it opens each conversation, and how it paces its turns. Every edit is saved to the agent’s draft automatically. Callers only hear your changes after you publish. New to Agents? Start with the Quickstart.

System prompt

The system prompt sets the personality, goals, and guardrails that steer every reply. It is capped at 32,000 tokens. The API rejects longer prompts with 422 Unprocessable Entity. Keeping it under 2,000 tokens is recommended: shorter prompts cut latency and cost, and hold the model’s attention better. It can also be replaced for a single session by sending overrides.system_prompt when creating the session. To personalize the prompt per session without replacing it, write {{placeholders}}: custom variables such as {{customer_name}} take the values you pass when creating the session, and system variables such as {{system.caller_number}} or {{system.today}} are filled in by the platform.

Keep the prompt focused:

State who the agent is and what it should accomplish, in a few sentences each.
Spell out guardrails explicitly (“If asked about pricing, direct the caller to sales”).
Write for the ear: replies are spoken aloud, so ask for short, conversational answers.

First message

Choose how the agent opens each conversation:

Mode	Behavior	Field on the wire
Off	The agent stays silent and waits for the caller to speak first.	—
Fixed message	The agent opens with the exact text you provide, every time.	`first_message`
Prompt	The agent generates its opening line from instructions you provide.	`first_message_prompt`

first_message and first_message_prompt can each hold up to 10,000 characters. The active mode (first_message_mode: off, fixed, or prompt) decides what callers hear. Both fields accept the same {{placeholders}} as the system prompt (see Dynamic variables), and both can be replaced for a single session by sending overrides.first_message or overrides.first_message_prompt when creating the session.

Voice

The Voice panel selects the voice your agent speaks with (voice_id), its speaking language (speaking_language: one of the 52 supported languages), and whether it speaks expressively (expressive, default true). See Voice & language for picking a voice and Expressive mode for expressive delivery.

Conversation settings

Turn-taking

conversation.response_wait_ms (300–2000, default 550) is how long the agent waits after the caller pauses before it starts talking. In the Builder this is the Response wait slider, with Fast (0.45 s), Balanced (0.55 s), and Patient (0.9 s) shortcuts. When the agent thinks the caller is mid-sentence it waits longer, up to conversation.response_max_wait_ms (600–4000). Leave it null (the default) to follow the response wait plus 0.5 s; send 0 to clear an explicit value back to automatic. A max wait below the response wait is rejected with 422. conversation.eagerness is the same setting as a preset and still works: writing relaxed, balanced, or eager sets the response wait to 900, 550, or 450 ms, and reads report the preset that matches the current wait.

A short answer such as “yes” normally lands on the fast path. When the agent asks for digits or a spelled-out name, the wait is widened automatically so the caller can pause between groups.

conversation.speculative_response (default true) lets the agent start preparing its reply while the caller may still be speaking; the draft is discarded if they continue, and tools never run before the caller’s turn is confirmed. Turn it off if your custom LLM bills per token and you would rather not pay for discarded drafts. With it off, the response wait is added directly to every reply.

Interruptions

conversation.interruptible (default true): Whether the caller can barge in while the agent is speaking.
conversation.interruption_sensitivity sets how much caller speech counts as an interruption:
- low (Hard to interrupt in the Builder): The agent stops only for a firm, worded interjection, talking through background noise and short acknowledgements.
- balanced (default): Interrupts on normal speech.
- high (Easy to interrupt): The agent stops on the caller’s first word.
conversation.interruption_ignore_phrases (up to 50 entries of 40 characters): Backchannels such as "uh-huh" or "okay" that never interrupt the agent when the caller says only them. Matching ignores case and punctuation. Send [] to clear the list.

Call duration

conversation.max_duration_seconds (60–3600, default 1800) ends the session automatically when the limit is reached.

Preview calls in the Builder are capped at 10 minutes or this setting, whichever is lower.

Recording

conversation.record_audio (default true) stores per-speaker audio for playback and download, with a per-session override on the session request. In the console this lives under your agent’s Settings. Make sure callers are informed and consent where your jurisdiction requires it.

Timezone

conversation.timezone is the default IANA timezone (like Asia/Tokyo) the agent uses for dates and times in conversation. Leave it empty for automatic: each session follows the caller’s device or phone number, falling back to UTC. Set one when your agent serves a single region regardless of who calls. A per-session timezone on the session request overrides this. See Time & timezone for the full resolution order.

Autosave and publishing

There is no Save button. Each change is written to the agent’s draft moments after you stop editing, and the Saving… / Saved indicator at the bottom-left of the page shows the current state. If a save fails, the Builder tells you and keeps your pending edits so nothing is lost. Drafts never affect live traffic: active integrations keep using the last published version until you press Publish, which snapshots the draft as a new immutable version. The Publish button lights up whenever the draft differs from what is published. See Versions & publishing.

Configure through the API

The same draft is readable and writable over REST, which is useful for provisioning agents from your own systems.

Read the draft

Request

curl --request GET "https://api.fish.audio/v1/agent/agents/$AGENT_ID/config" \
  --header "Authorization: Bearer $FISH_API_KEY"

Response (abridged)

{
  "config_hash": "sha256:5f2c1a9e…",
  "prompt": {
    "system_prompt": "You are Aria, a friendly support agent for Acme…",
    "first_message_mode": "fixed",
    "first_message": "Hi, thanks for calling Acme. How can I help?"
  },
  "voice": {
    "voice_id": "802e3bc2b27e49c2995d23ef70e6ac89",
    "speaking_language": "en"
  },
  "conversation": {
    "max_duration_seconds": 1800,
    "response_wait_ms": 550,
    "response_max_wait_ms": null,
    "eagerness": "balanced",
    "interruptible": true,
    "interruption_sensitivity": "balanced",
    "interruption_ignore_phrases": [],
    "speculative_response": true,
    "timezone": ""
  }
}

The response also includes the tools, knowledge_base, analysis, and webhooks sections, each covered on its own page. config_hash identifies this draft revision; a mismatch with the published version is what marks an agent as having unpublished changes.

Update sections

PATCH takes a partial body and deep-merges it into the draft: send only the sections and fields you want to change, and everything else keeps its value. Fields that hold a list (webhooks.post_call among them) are replaced as a whole, so send the complete list whenever you change one.

curl --request PATCH "https://api.fish.audio/v1/agent/agents/$AGENT_ID/config" \
  --header "Authorization: Bearer $FISH_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "prompt": { "system_prompt": "You are Aria, a concise support agent for Acme." },
    "conversation": { "response_wait_ms": 900 }
  }'

The response includes the draft’s new config_hash. Values outside the documented limits (a system prompt over 32,000 tokens, max_duration_seconds outside 60–3600) are rejected with 422 Unprocessable Entity and the draft is left unchanged.

Config sections

Section	What it holds	Documented in
`prompt`	System prompt and first-message settings	This page
`voice`	Voice profile, speaking language, and expressive mode	Voice & language
`conversation`	Call duration, turn-taking, interruption behavior, timezone, and storage	This page; storage in Conversation history
`tools`	Attached webhook tools and system tool switches	Tools
`knowledge_base`	Attached knowledge sources	Knowledge base
`analysis`	Post-call summary, data fields, and success criteria	Post-call analysis
`webhooks`	Post-call webhook delivery and the inbound call webhook	Webhooks
`llm`	Conversation model settings, including a custom LLM endpoint	Custom LLM

Going further

Voice & language

Choose a voice profile and control the speaking language.

Versions & publishing

Turn the draft into an immutable live version.

Preview calls

Talk to your draft in the Builder before publishing.

Tools

Let the agent call your backend mid-conversation.

Dynamic variables

Personalize the prompt and first message per session.

Get Started

Build

Test

Deploy

Telephony

Monitor

System prompt

First message

Voice

Conversation settings

Turn-taking

Interruptions

Call duration

Recording

Timezone

Autosave and publishing

Configure through the API

Read the draft

Update sections

Config sections

Going further

Voice & language

Versions & publishing

Preview calls

Tools

Dynamic variables

​System prompt

​First message

​Voice

​Conversation settings

​Turn-taking

​Interruptions

​Call duration

​Recording

​Timezone

​Autosave and publishing

​Configure through the API

​Read the draft

​Update sections

​Config sections

​Going further

Voice & language

Versions & publishing

Preview calls

Tools

Dynamic variables

System prompt

First message

Voice

Conversation settings

Turn-taking

Interruptions

Call duration

Recording

Timezone

Autosave and publishing

Configure through the API

Read the draft

Update sections

Config sections

Going further