fishaudio · Him188 · Sep 20, 2026 · Sep 20, 2026 · coderabbitai · Sep 20, 2026
diff --git a/agents/build/configuration.mdx b/agents/build/configuration.mdx
@@ -69,9 +69,9 @@
 
 ### Timezone
 
-`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.
+`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](/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.


diff --git a/agents/build/dynamic-variables.mdx b/agents/build/dynamic-variables.mdx
@@ -32,7 +32,7 @@
 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; the dotted `system.*` names are reserved for [system variables](#system-variables)), 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)
@@ -94,17 +94,17 @@
 ```

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

 ## System variables

 The platform fills a handful of `{{system.*}}` placeholders itself, on every session. You cannot supply or override them: the names you pass in `dynamic_variables` cannot contain a dot, so the two namespaces never collide.

 | Variable | Value | Notes |
 |---|---|---|
 | `system.channel` | `phone_inbound`, `phone_outbound`, or `web_voice` | Web SDK, API, preview, and agent test sessions are all `web_voice`. |
-| `system.timezone` | The session's resolved IANA timezone, for example `Asia/Shanghai` | `UTC` when nothing resolves. Always equals the session's `timezone` field; see [which timezone a session uses](/agents/build/time-timezone#which-timezone-a-session-uses). |
+| `system.timezone` | The session's resolved IANA timezone, for example `Asia/Tokyo` | `UTC` when nothing resolves. Always equals the session's `timezone` field; see [which timezone a session uses](/agents/build/time-timezone#which-timezone-a-session-uses). |
 | `system.today` | Today's date in that timezone, ISO 8601 `YYYY-MM-DD` | The calendar date at session creation. There is no `system.now`; see [World context](#world-context). |
 | `system.language` | The session language code, one of the [52 supported languages](/agents/build/voice-language#speaking-language) |
  The `language` [override](/agents/deploy/authenticated-sessions#overrides) when the request carries one, otherwise the agent's [speaking language](/agents/build/voice-language#speaking-language). |
@@ -155,12 +155,12 @@
 A reference to a system variable that does not exist (`{{system.foo}}`) is rejected with `422` when you save the configuration or the tool, and when you send it in session overrides. The error lists the available names.

 <Note>
 There is no `system.session_id`. The configuration is rendered before the session receives its id, so the id cannot be templated into it. Read it from the `POST /v1/agent/sessions` [response](/agents/deploy/authenticated-sessions), the SDK's `connect` event, or the `session` object in [webhooks](/agents/monitor/webhooks).
 </Note>

 ## World context

 The agent knows the current date and time without any variable. The platform states the date and the session's timezone at the start of every session and refreshes the time on every turn, so "tomorrow morning" or "next Tuesday" resolve correctly even in a long conversation. You don't need a custom `{{today}}` or `{{now}}`, and there is no `system.now`: variables render once, when the session is created, so a templated time would be stale from the first reply onward. When you want the date or timezone as text in a template, for example in a webhook tool URL, use the [`system.today` and `system.timezone`](#system-variables) system variables.

 See [Time & timezone](/agents/build/time-timezone) for how the timezone is resolved and how to turn the injection off for a session (`world_context: false`).


diff --git a/agents/build/time-timezone.mdx b/agents/build/time-timezone.mdx
@@ -6,14 +6,21 @@
 
 Agents are time-aware out of the box: every session knows today's date and the current time in the session's timezone. You don't reference a variable or add anything to your prompt: "tomorrow morning" and "next Tuesday" ground correctly from the first turn, on every channel (voice, text, and phone).
 
+<Note>
+  The default timezone is **UTC**. Change it for the agent in its
+  [configuration](/agents/build/configuration#timezone), and override it for a
+  single session with `timezone` in the creation request. See
+  [Which timezone a session uses](#which-timezone-a-session-uses).
+</Note>
+
 ## What the agent knows
 
 Fish Audio injects two pieces of world context server-side:
 
 | When | What | Example |
 | ------------------ | ---------------------------- | ------------------------------------------------------------------ |
-| At session start | Today's date and the session timezone | `Today is Thursday, July 23, 2026. Session timezone: Asia/Shanghai (UTC+8).` |
-| Before every reply | The current time, minute precision | `Current date and time: Thursday, July 23, 2026 at 13:00 (Asia/Shanghai).` |
+| At session start | Today's date and the session timezone | `Today is Thursday, July 23, 2026. Session timezone: Asia/Tokyo (UTC+9).` |
+| Before every reply | The current time, minute precision | `Current date and time: Thursday, July 23, 2026 at 13:00 (Asia/Tokyo).` |
 
 The time is refreshed on every turn, so it stays accurate through long conversations and past midnight.
 
@@ -22,13 +29,13 @@
  system prompt's character limit.
 </Note>

 Both facts also exist as [system variables](/agents/build/dynamic-variables#system-variables) for the cases where you want to template them yourself, for example into a webhook tool's URL: `{{system.today}}` is the date at session creation as ISO `YYYY-MM-DD`, and `{{system.timezone}}` is the resolved IANA name (`UTC` when nothing resolves). There is no `{{system.now}}`: variables render once, when the session is created, so a templated clock would freeze at the opening. The per-turn time above is the one to rely on.

 ## Which timezone a session uses
 
 The timezone is resolved once, when the session is created, taking the first that applies:
 
-1. **`timezone`** in the creation request: your explicit per-session choice, as an IANA name like `Asia/Shanghai`. An invalid name rejects the request with `422`.
+1. **`timezone`** in the creation request: your explicit per-session choice, as an IANA name like `Asia/Tokyo`. An invalid name rejects the request with `422`.
 2. **The agent's configured timezone**: set on the agent in the Builder (**Configuration → Timezone**) or via the [agent config API](/agents/build/configuration). Pin one when your agent serves a single region regardless of who calls.
 3. **`client_timezone`**: a hint with the end user's browser timezone, sent automatically by the [Web SDK](/agents/deploy/web-sdk) in public-agent mode. Used only when neither of the above is set; an invalid hint is ignored rather than failing the session.
 4. **The caller's phone number**: inbound calls infer the timezone from the caller's country when that country has a single timezone.
@@ -44,7 +51,7 @@
   --header "Content-Type: application/json" \
   --data '{
     "agent_id": "YOUR_AGENT_ID",
-    "timezone": "Asia/Shanghai"
+    "timezone": "Asia/Tokyo"
   }'
 ```
 

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
@@ -28,7 +28,8 @@
 <Steps>
   <Step title="Create a session from your backend">
     Call `POST /v1/agent/sessions` with your API key. This is where you set
-    per-session parameters: user identity, overrides, dynamic variables.
+    per-session parameters: user identity, timezone, overrides, dynamic
+    variables.
   </Step>
   <Step title="Return the response to your frontend">
     The response is the session token. Forward it verbatim.
@@ -47,6 +48,7 @@
   --data '{
     "agent_id": "YOUR_AGENT_ID",
     "end_user_id": "user_42",
+    "timezone": "Asia/Tokyo",
     "dynamic_variables": { "name": "Ada" }
   }'
 ```
@@ -62,6 +64,7 @@
     body: JSON.stringify({
       agent_id: "YOUR_AGENT_ID",
       end_user_id: req.user.id,
+      timezone: req.user.timezone, // IANA name, like "Asia/Tokyo"
       dynamic_variables: { name: req.user.name },
     }),
   });
@@ -77,13 +80,14 @@
 import os
 import requests
 
-def create_voice_session(end_user_id: str, name: str) -> dict:
+def create_voice_session(end_user_id: str, name: str, timezone: str) -> dict:
     response = requests.post(
         "https://api.fish.audio/v1/agent/sessions",
         headers={"Authorization": f"Bearer {os.environ['FISH_API_KEY']}"},
         json={
             "agent_id": "YOUR_AGENT_ID",
             "end_user_id": end_user_id,
+            "timezone": timezone,  # IANA name, like "Asia/Tokyo"
             "dynamic_variables": {"name": name},
         },
     )
@@ -93,6 +97,8 @@
 
 </CodeGroup>
 
+`timezone` overrides the agent's configured timezone for this session, so the agent speaks in your user's local date and time. The default is UTC: see [Time & timezone](/agents/build/time-timezone).
+
 On the client, fetch the token from your backend and pass it to the SDK unchanged:
 
 ```javascript Browser
@@ -109,7 +115,7 @@

 <Note>
  `overrides`, `dynamic_variables`, `tool_events`, `timezone`, and
  `world_context` belong in your backend's creation request. The SDK forwards
  these options (and its `language` shorthand for `overrides.language`) only in
  [public agent](/agents/deploy/public-agents) mode.
 </Note>
@@ -119,16 +125,16 @@
 | 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`.                                                                       |
 | `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, up to 256 characters. Stored on the session and echoed in [webhook](/agents/monitor/webhooks) payloads and [custom LLM](/agents/build/custom-llm) requests.                                                                                             |
 | `metadata`          | object, optional  | Your own key-value namespace. Stored and returned verbatim on session queries and webhooks, never read or interpreted by the platform.                                                                                                                                                   |
 | `llm_extra_body`    | object, optional  | JSON object (at most 16 KB) forwarded verbatim to your [custom LLM](/agents/build/custom-llm) endpoint on every request as `fishaudio_extra_body`, for example the chat or thread the user is in. Not stored or returned on session reads; ignored when the agent uses a platform model. |
 | `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; 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). |
+| `timezone`          | string, optional  | IANA timezone (like `Asia/Tokyo`) 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 device timezone as an IANA name. A hint, not a demand: it applies only when neither `timezone` nor the agent's configured timezone is set, and invalid values are ignored. The SDK fills it automatically in public-agent mode. From your backend, forward the value from your client. See the [resolution order](/agents/build/time-timezone). |
 | `world_context`     | boolean, optional | Whether the agent knows the current date and time. Default `true`; set `false` to withhold both from this session.                                                                                                                                                                        |
 
 Unknown fields (top-level or inside `overrides`) are rejected with `422`.
@@ -151,7 +157,7 @@
  "agent_id": "YOUR_AGENT_ID",
  "overrides": {
    "first_message": "Welcome back, {{name}}, picking up where we left off.",
    "voice_id": "802e3bc2b27e49c2995d23ef70e6ac89",
    "language": "ja"
  }
 }
@@ -216,7 +222,7 @@

 | Status | Meaning                                                                                                                                       |
 | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
 | `400`  | A keyless (public-agent) request sent an override [public sessions don't accept](#overrides), or a `name`.                                    |
 | `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/quickstart.mdx b/agents/quickstart.mdx
@@ -10,7 +10,7 @@

 - A Fish Audio account. Agents is in public beta and open to every account, no application needed.
 - For the API path: a Fish Audio API key. Create one under [API keys](https://fish.audio/app/api-keys/) in the console
 - Every account starts with a $5 trial balance, about 60 minutes of agent conversation. It pays for web, phone, and API sessions at the normal rates, including token-billed LLMs. After that, usage is billed per second against your API credit.

 <Tabs>
  <Tab title="Dashboard">
@@ -84,9 +84,11 @@
         curl --request POST https://api.fish.audio/v1/agent/sessions \
           --header "Authorization: Bearer $FISH_API_KEY" \
           --header "Content-Type: application/json" \
-          --data '{ "agent_id": "'$AGENT_ID'" }'
+          --data '{ "agent_id": "'$AGENT_ID'", "timezone": "Asia/Tokyo" }'
         ```
 
+        `timezone` overrides the agent's timezone for this session: replace it with your user's IANA timezone. The default is UTC, which you can change in the agent's configuration. See [Time & timezone](/agents/build/time-timezone).
+
         ```json Response
         {
           "session_id": "...",
@@ -149,7 +151,10 @@
               Authorization: `Bearer ${process.env.FISH_API_KEY}`,
               "Content-Type": "application/json",
             },
-            body: JSON.stringify({ agent_id: process.env.AGENT_ID }),
+            body: JSON.stringify({
+              agent_id: process.env.AGENT_ID,
+              timezone: "Asia/Tokyo", // your user's IANA timezone
+            }),
           });
           if (!upstream.ok) {
             console.error("session creation failed:", upstream.status);