diff --git a/agents/build/configuration.mdx b/agents/build/configuration.mdx index ed07406..60cc3a6 100644 --- a/agents/build/configuration.mdx +++ b/agents/build/configuration.mdx @@ -69,7 +69,7 @@ The Voice panel selects the voice your agent speaks with (`voice_id`), its speak ### 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 diff --git a/agents/build/dynamic-variables.mdx b/agents/build/dynamic-variables.mdx index ad4cb1e..4ed9f4a 100644 --- a/agents/build/dynamic-variables.mdx +++ b/agents/build/dynamic-variables.mdx @@ -104,7 +104,7 @@ The platform fills a handful of `{{system.*}}` placeholders itself, on every ses | 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). | diff --git a/agents/build/time-timezone.mdx b/agents/build/time-timezone.mdx index fae1fad..c1f0a95 100644 --- a/agents/build/time-timezone.mdx +++ b/agents/build/time-timezone.mdx @@ -6,14 +6,21 @@ icon: "clock" 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). + + 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). + + ## 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. @@ -28,7 +35,7 @@ Both facts also exist as [system variables](/agents/build/dynamic-variables#syst 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 @@ curl --request POST https://api.fish.audio/v1/agent/sessions \ --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 index 88cea7d..c5dff2b 100644 --- a/agents/deploy/authenticated-sessions.mdx +++ b/agents/deploy/authenticated-sessions.mdx @@ -28,7 +28,8 @@ Your backend exchanges your API key for a single-conversation token. 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. The response is the session token. Forward it verbatim. @@ -47,6 +48,7 @@ curl --request POST https://api.fish.audio/v1/agent/sessions \ --data '{ "agent_id": "YOUR_AGENT_ID", "end_user_id": "user_42", + "timezone": "Asia/Tokyo", "dynamic_variables": { "name": "Ada" } }' ``` @@ -62,6 +64,7 @@ app.post("/api/voice-session", async (req, res) => { 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 @@ app.post("/api/voice-session", async (req, res) => { 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 @@ def create_voice_session(end_user_id: str, name: str) -> dict: +`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 @@ -127,8 +133,8 @@ More on what the SDK can do once connected is in the [Web SDK](/agents/deploy/we | `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`. diff --git a/agents/quickstart.mdx b/agents/quickstart.mdx index 0b791a5..30d2646 100644 --- a/agents/quickstart.mdx +++ b/agents/quickstart.mdx @@ -84,9 +84,11 @@ Build a voice agent and talk to it in a few minutes. Use the console for a no-co 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 @@ Build a voice agent and talk to it in a few minutes. Use the console for a no-co 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);