fishaudio · Him188 · Aug 6, 2026 · Aug 6, 2026 · Aug 6, 2026 · Aug 6, 2026
diff --git a/agents/build/configuration.mdx b/agents/build/configuration.mdx
@@ -32,7 +32,7 @@
 
 ## Voice
 
-The Voice panel selects the voice profile your agent speaks with (`voice_profile_id`) and its speaking language (`speaking_language`: `en`, `ja`, `zh`, `ko`, `es`, `fr`, `de`). See [Voice & language](/agents/build/voice-language) for picking a voice and how automatic language detection interacts with this setting.
+The Voice panel selects the voice your agent speaks with (`voice_id`) and its speaking language (`speaking_language`: `en`, `ja`, `zh`, `ko`, `es`, `fr`, `de`). See [Voice & language](/agents/build/voice-language) for picking a voice and how automatic language detection interacts with this setting.
 
 ## Conversation settings
 
@@ -68,7 +68,7 @@

 `conversation.timezone` is the default IANA timezone (like `Asia/Shanghai`) 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](/agents/build/time-timezone) overrides this. See [Time & timezone](/agents/build/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.

@@ -94,7 +94,7 @@
     "first_message": "Hi, thanks for calling Acme. How can I help?"
   },
   "voice": {
-    "voice_profile_id": "802e3bc2b27e49c2995d23ef70e6ac89",
+    "voice_id": "802e3bc2b27e49c2995d23ef70e6ac89",
     "speaking_language": "en"
   },
   "conversation": {

diff --git a/agents/build/dynamic-variables.mdx b/agents/build/dynamic-variables.mdx
@@ -1,26 +1,17 @@
 ---
-title: "Dynamic Variables & Overrides"
-description: "Personalize each session with template variables and per-session configuration overrides"
+title: "Dynamic Variables"
+description: "Personalize each session with template variables supplied at creation time"
 icon: "brackets-curly"
 ---
 
-An agent's published configuration is shared by every caller — but each session can be personalized at creation time. Two mechanisms cover this, and both travel in the same `POST /v1/agent/sessions` request:
-
-| Mechanism | What it does | Gated by |
-|---|---|---|
-| `dynamic_variables` | Fills `{{placeholder}}` templates in your configuration text | Nothing per-agent — no allowlist |
-| `overrides` | Replaces whole configuration fields for this session | Per-agent allowlist of overridable fields |
-
-## Dynamic variables
-
-Write `{{variable_name}}` placeholders in your agent's system prompt or first message and supply values when you create the session. Substitution happens once, when the published configuration is assembled for the session.
+An agent's published configuration is shared by every caller — dynamic variables personalize it per session. Write `{{variable_name}}` placeholders in your agent's system prompt or first message and supply values when you create the session. Substitution happens once, when the published configuration is assembled for the session.
 
 ```text System prompt
 You are a support agent for {{company}}. The caller's name is {{customer_name}}
 and they are on the {{plan}} plan. Greet them by name.
 ```

 Pass values as a flat object of strings, numbers, or booleans. Variable names must match `[A-Za-z][A-Za-z0-9_]*` (no hyphens or dots), string values are capped at 1,000 characters, and a request can carry at most 50 variables — violations reject session creation with `422`:

 <CodeGroup>
 ```bash API (curl)
@@ -60,61 +51,18 @@
 You don't need a variable for the current date or time — the agent already knows both, in the session's timezone. See [Time & timezone](/agents/build/time-timezone).
 </Tip>
 
-## Overrides
-
-Overrides replace configuration fields wholesale for one session — for example, forcing a different language for a caller. Because they change agent behavior, each agent declares which fields callers may override; everything else is rejected.
-
-<CodeGroup>
-```bash API (curl)
-curl --request POST https://api.fish.audio/v1/agent/sessions \
-  --header "Authorization: Bearer $FISH_API_KEY" \
-  --header "Content-Type: application/json" \
-  --data '{
-    "agent_id": "YOUR_AGENT_ID",
-    "overrides": { "language": "ja" }
-  }'
-```
-
-```javascript JavaScript SDK
-import { AgentSession } from "@fishaudio/agent-client";
-
-const session = await AgentSession.start({
-  agentId: "YOUR_AGENT_ID",
-  overrides: { language: "ja" },
-});
-```
-</CodeGroup>
-
-### The `language` shorthand
-
-Overriding the session language is common enough that the request accepts a top-level `language` field as shorthand for `overrides.language`. Both forms pass through the same allowlist gate — if `language` is not overridable on the agent, both are rejected.
-
-```json
-{ "agent_id": "YOUR_AGENT_ID", "language": "ja" }
-```
-
-### Validation
-
-| Case | Result |
-|---|---|
-| Override field not on the agent's allowlist | `400` |
-| Unknown field inside `overrides` | `422` |
-| Unknown top-level field in the request | `422` |
-
-<Note>
-The session record stores which overrides took effect.
-</Note>
+Variables fill placeholders in the configured text. To replace whole configuration fields for a session — the prompt itself, the opener, voice, language — use [overrides](/agents/deploy/authenticated-sessions#overrides) on the same request; `{{placeholders}}` render inside overridden text too.
 
 ## Who supplies the values
 
-Where variables and overrides come from depends on the session's [access mode](/agents/deploy/overview#who-may-start-sessions):
+Where variable values come from depends on the session's [access mode](/agents/deploy/overview#who-may-start-sessions):
 
-| Mode | Who creates the session | Who supplies variables and overrides |
+| Mode | Who creates the session | Who supplies the values |
 |---|---|---|
 | `agentId` ([public agents](/agents/deploy/public-agents)) | The SDK, directly from the browser | The browser, via `AgentSession.start()` options |
 | `sessionToken` (private agents) | Your backend, with your API key | Your backend, in its `POST /v1/agent/sessions` call |
 
-In `sessionToken` mode the SDK's `overrides`, `dynamicVariables`, and `language` options have no effect — the session already exists by the time the token reaches the browser. Attach personalization server-side instead:
+In `sessionToken` mode the SDK's `dynamicVariables` option has no effect — the session already exists by the time the token reaches the browser. Attach personalization server-side instead:
 
 ```javascript Backend (sessionToken mode)
 // Your backend endpoint, called by your own frontend
@@ -127,28 +75,27 @@
   body: JSON.stringify({
     agent_id: "YOUR_AGENT_ID",
     dynamic_variables: { customer_name: user.name, plan: user.plan },
-    overrides: { language: user.locale },
   }),
 });
 const sessionToken = await response.json(); // pass to AgentSession.start({ sessionToken })
 ```
 
 <Tip>
-In `agentId` mode, values arrive from the end user's browser — treat them as untrusted input. Keep the override allowlist limited to fields you are comfortable letting anyone set, and use `sessionToken` mode when personalization must come from data only your backend knows.
+In `agentId` mode, values arrive from the end user's browser — treat them as untrusted input, and use `sessionToken` mode when personalization must come from data only your backend knows.
 </Tip>
 
 ## Going further
 
 <CardGroup cols={2}>
   <Card title="Agent configuration" icon="sliders" href="/agents/build/configuration">
-    The fields your placeholders and overrides act on.
+    The fields your placeholders act on.
   </Card>
   <Card
-    title="Authenticated sessions"
+    title="Overrides"
     icon="server"
-    href="/agents/deploy/authenticated-sessions"
+    href="/agents/deploy/authenticated-sessions#overrides"
   >
-    Set variables from your backend when creating the session.
+    Replace whole configuration fields for one session.
   </Card>
   <Card title="Versions & publishing" icon="code-branch" href="/agents/deploy/versions-publishing">
     Sessions assemble the published configuration.

diff --git a/agents/build/voice-language.mdx b/agents/build/voice-language.mdx
@@ -39,7 +39,7 @@ The voice picker on the **Configuration** page has two levels: a curated list fo
 
 ## Use any voice model
 
-The agent's voice is a **voice model id** (`voice_profile_id`) — the same ids used as `reference_id` in [Text to Speech](/features/text-to-speech). Any public voice model from the Voice Library works, including:
+The agent's voice is a **voice model id** (`voice_id`) — the same ids used as `reference_id` in [Text to Speech](/features/text-to-speech). Any public voice model from the Voice Library works, including:
 
 - **Library voices** — ready-made public voices. Find ids in the [Voice Library](/features/manage-voices).
 - **Your cloned voices** — [clone a voice](/features/voice-cloning) once, then use its model id as your agent's voice.
@@ -55,7 +55,7 @@ curl --request PATCH "https://api.fish.audio/v1/agent/agents/$AGENT_ID/config" \
   --header "Content-Type: application/json" \
   --data '{
     "voice": {
-      "voice_profile_id": "802e3bc2b27e49c2995d23ef70e6ac89"
+      "voice_id": "802e3bc2b27e49c2995d23ef70e6ac89"
     }
   }'
 ```
@@ -80,6 +80,8 @@ curl --request PATCH "https://api.fish.audio/v1/agent/agents/$AGENT_ID/config" \
   The voice model and the speaking language are independent settings: picking a voice does not change the language, and vice versa. Choose a voice that sounds natural in the language you configure.
 </Note>
 
+Both settings can also be replaced for a single session — send `overrides.voice_id` or `overrides.language` on the session request. See [Overrides](/agents/deploy/authenticated-sessions#overrides).
+
 ## Going further
 
 <CardGroup cols={2}>

diff --git a/agents/deploy/authenticated-sessions.mdx b/agents/deploy/authenticated-sessions.mdx
@@ -18,7 +18,7 @@
 <Note>
  No backend, and anyone may talk to the agent? A [public
  agent](/agents/deploy/public-agents) lets the SDK create sessions with just an
  `agentId` — no token involved, gated by an origin allowlist and rate limits.
 </Note>

 ## Create a token on your backend
@@ -109,7 +109,7 @@

 <Note>
  `overrides`, `dynamic_variables`, `language`, `tool_events`, `timezone`, and
  `world_context` belong in your backend's creation request — the SDK forwards
  these options only in [public agent](/agents/deploy/public-agents) mode.
 </Note>

@@ -118,13 +118,12 @@
 | Field               | Type              | Description                                                                                                                                                                                                                                                                               |
 | ------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `agent_id`          | string, required  | The agent to talk to. It must have a [published version](/agents/deploy/versions-publishing).                                                                                                                                                                                             |
 | `name`              | string, optional  | Display name for this session in the console's Conversations list, up to 128 characters. Omit it to show the session's start time instead. API-key requests only — keyless (public) creation rejects it with `400`.                                                                       |
-| `language`          | string, optional  | Shorthand for `overrides.language`; subject to the same override allow-list. See [Voice & language](/agents/build/voice-language).                                                                                                                                                        |
-| `overrides`         | object, optional  | Per-session config overrides. Each field must be enabled in the agent's override allow-list — unauthorized fields are rejected with `400`.                                                                                                                                                |
+| `overrides`         | object, optional  | Replace parts of the published configuration for this session — see [Overrides](#overrides).                                                                                                                                                                                              |
 | `dynamic_variables` | object, optional  | Up to 50 entries of string, number, or boolean values, substituted into `{{placeholders}}`. See [Dynamic variables](/agents/build/dynamic-variables).                                                                                                                                     |
 | `tool_events`       | boolean, optional | Stream tool lifecycle events (`toolCallStarted` / `toolCallCompleted` / `toolCallFailed`) to the client. Default `true`; set `false` to keep tool inputs and outputs off the client.                                                                                                      |
 | `end_user_id`       | string, optional  | Your identifier for the end user, for attribution in [conversation history](/agents/monitor/conversation-history).                                                                                                                                                                        |
 | `metadata`          | object, optional  | Your own key-value namespace. Stored and returned verbatim on session queries and webhooks — never read or interpreted by the platform.                                                                                                                                                   |
 | `record_audio`      | boolean, optional | Whether to record this session's audio. Overrides the agent's [recording setting](/agents/monitor/conversation-history#what-gets-stored) for this session only — it never changes the agent; omit it to use the agent's configuration.                                                    |
 | `timezone`          | string, optional  | IANA timezone (like `Asia/Shanghai`) for the agent's sense of local time. Invalid names are rejected with `422`. See [Time & timezone](/agents/build/time-timezone).                                                                                                                      |
 | `client_timezone`   | string, optional  | The end user's browser timezone, filled automatically by the SDK in public-agent mode. A hint, not a demand: it applies only when neither `timezone` nor the agent's configured timezone is set, and invalid values are ignored. See the [resolution order](/agents/build/time-timezone). |
@@ -132,6 +131,35 @@
 
 Unknown fields — top-level or inside `overrides` — are rejected with `422`.
 
+## Overrides
+
+`overrides` replaces parts of the agent's published configuration for one session — the agent itself never changes:
+
+| Field                  | Type                                     | Effect for this session                                                                                                                                                                                           |
+| ---------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `first_message`        | string, up to 10,000 characters          | The agent opens with exactly this text, spoken verbatim — whatever first-message mode the configuration sets. `{{placeholders}}` render inside it.                                                                |
+| `first_message_prompt` | string, up to 10,000 characters          | Instructions the agent generates its opener from, replacing the configured first-message behavior. `{{placeholders}}` render inside it. Mutually exclusive with `first_message` — sending both is `422`.          |
+| `system_prompt`        | string, up to 8,000 characters           | Replaces the configured system prompt entirely. `{{placeholders}}` render inside it.                                                                                                                              |
+| `voice_id`             | string                                   | The voice the agent speaks with — any [voice model id](/agents/build/voice-language#use-any-voice-model) from the Voice Library. Voices bias pronunciation toward their own language, so pair it with `language`. |
+| `language`             | `en`, `ja`, `zh`, `ko`, `es`, `fr`, `de` | Pins the conversation language, taking precedence over the configured [speaking language](/agents/build/voice-language#speaking-language) and automatic language detection.                                       |
+
+```json
+{
+  "agent_id": "YOUR_AGENT_ID",
+  "overrides": {
+    "first_message": "Welcome back, {{name}} — picking up where we left off.",
+    "voice_id": "802e3bc2b27e49c2995d23ef70e6ac89",
+    "language": "ja"
+  }
+}
+```
-```json
-{
-  "agent_id": "YOUR_AGENT_ID",
-  "overrides": {
-    "first_message": "Welcome back, {{name}} — picking up where we left off.",
-    "voice_id": "802e3bc2b27e49c2995d23ef70e6ac89",
-    "language": "ja"
-  }
-}
-```
-```json
-{
-  "agent_id": "YOUR_AGENT_ID",
-  "overrides": {
-    "first_message": "Welcome back, {{name}} — picking up where we left off.",
-    "voice_id": "802e3bc2b27e49c2995d23ef70e6ac89",
-    "language": "ja"
-  }
-}
-```
+
+On [public agents](/agents/deploy/public-agents), keyless (browser-created) sessions may override only `language` and `voice_id` — the prompt-shaping fields are rejected with `400` regardless of the agent. Create the session from your backend to use them.
+
+The session record stores which overrides took effect.
+
+Everything else on the request is not an override: `dynamic_variables`, `timezone`, `record_audio`, and `tool_events` are separate top-level fields. Session length is not settable per session — `max_duration_seconds` comes from the agent's [conversation configuration](/agents/build/configuration#call-duration).
+
 ## Response
 
 ```json JSON
@@ -187,7 +215,7 @@
 
 | Status | Meaning                                                                                                                                       |
 | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| `400`  | An `overrides` field is not on the agent's override allow-list.                                                                               |
+| `400`  | An `overrides` field is not enabled for this agent, or a keyless request sent an override [public sessions don't accept](#overrides).         |
 | `401`  | Invalid API key. A request with no `Authorization` header at all is treated as a public-agent request instead.                                |
 | `402`  | Quota exceeded.                                                                                                                               |
 | `403`  | Public-agent request rejected: the agent is not public, or the page's `Origin` is not on the allow-list.                                      |

diff --git a/agents/deploy/public-agents.mdx b/agents/deploy/public-agents.mdx
@@ -4,7 +4,7 @@
 icon: "globe"
 ---

 A public agent accepts sessions straight from the browser: the SDK calls the session endpoint with just an `agent_id` — no API key, no server of your own. The platform gates access with three controls: an agent-level public switch (off by default), a required origin allowlist, and rate limiting.

 Use this mode for demos, marketing pages, and support bubbles where standing up a backend isn't worth it. For production apps with their own users, [authenticated sessions](/agents/deploy/authenticated-sessions) are usually the better fit — see [when to use session tokens instead](#when-to-use-session-tokens-instead).

@@ -23,7 +23,7 @@
  </Step>
  <Step title="Add allowed origins">
    On the same page, list every web origin that may start sessions under
    **Allowed origins** (`allowed_origins` in the API). The allowlist is
    **required**: a request whose `Origin` doesn't match any entry is rejected
    with `403`.
  </Step>
@@ -62,7 +62,7 @@

 An entry matches only on **exact scheme + host + port**. The host is case-insensitive, and a trailing slash on an entry is tolerated — everything else must match exactly.

 | Allowlist entry           | Browser origin                 | Allowed                        |
 | ------------------------- | ------------------------------ | ------------------------------ |
 | `https://app.example.com` | `https://app.example.com`      | Yes                            |
 | `https://app.example.com` | `https://APP.example.com`      | Yes — host is case-insensitive |
@@ -90,11 +90,11 @@
  backend becomes the gate, and the platform-side public limits no longer apply.
 </Note>
 
 ## Treat public input as untrusted
 
-On the public path, the entire session request originates in the visitor's browser. The platform enforces its own guardrails — `overrides` are filtered against the agent's allowlist and unauthorized fields are rejected with `400` — but anything that passes through verbatim is attacker-controllable:
+On the public path, the entire session request originates in the visitor's browser. The platform enforces its own guardrails — public sessions accept only the `language` and `voice_id` [overrides](/agents/deploy/authenticated-sessions#overrides), rejecting everything else with `400` — but anything that passes through verbatim is attacker-controllable:
 
 - **`metadata`** is stored and returned exactly as sent, never interpreted by the platform. When you read it back in [conversation history](/agents/monitor/conversation-history) or [webhooks](/agents/monitor/webhooks), treat it as untrusted data — never as proof of who the visitor is.
 - **`dynamic_variables`** are chosen by the page that starts the session. Don't inject anything through them that the visitor shouldn't control. See [Dynamic variables](/agents/build/dynamic-variables).

 For trusted attribution (a verified `end_user_id`, server-set metadata), create sessions from your backend instead.

diff --git a/agents/deploy/react-sdk.mdx b/agents/deploy/react-sdk.mdx
@@ -86,7 +86,7 @@
 }
 ```

 `status`, `mode`, and `isSpeaking` are React state — your component re-renders as the conversation progresses. When the component unmounts, the session ends automatically.

 <Note>
  Call `startSession` from a user gesture (such as a click handler) so the
@@ -103,7 +103,7 @@
 await startSession({ sessionToken });
 ```
 
-See [Authenticated sessions](/agents/deploy/authenticated-sessions) for the backend side. `startSession` accepts the same options as `AgentSession.start` in the [Web SDK](/agents/deploy/web-sdk), including [`clientTools`](/agents/build/client-tools). Session settings such as `overrides` and `dynamicVariables` apply when you connect with an `agentId`; with a `sessionToken`, your backend sets them in its session-creation request instead.
+See [Authenticated sessions](/agents/deploy/authenticated-sessions) for the backend side. `startSession` accepts the same options as `AgentSession.start` in the [Web SDK](/agents/deploy/web-sdk), including [`clientTools`](/agents/build/client-tools). Session settings such as [`overrides`](/agents/deploy/authenticated-sessions#overrides) and `dynamicVariables` apply when you connect with an `agentId`; with a `sessionToken`, your backend sets them in its session-creation request instead.
 
 ## What `useConversation` returns