docs: session overrides — field reference, voice_id rename, public cap - #119
Conversation
Document the overridable fields in the session-creation flow (previously just "an object gated by an allowlist"), and align with the API revision: voice_profile_id → voice_id everywhere, first_message_prompt added, top-level language sugar removed from the wire (SDK option folds into overrides), public sessions capped to language + voice_id. The per-agent allowlist setting stays undocumented; pages describe the 400 behavior only. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
📝 WalkthroughWalkthroughThe PR updates the OpenAPI schema and agent documentation to use ChangesVoice and session override updates
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@agents/build/dynamic-variables.mdx`:
- Around line 9-12: Update the overrides row in the comparison table to
accurately reflect the later field list: state that there are five overridable
fields, or describe four mutually exclusive categories and clarify that
first_message and first_message_prompt share one category.
In `@agents/deploy/authenticated-sessions.mdx`:
- Line 143: Update the voice_id field description in the overrides table to
document the 256-character maximum enforced by the OpenAPI schema, while
preserving the existing voice model and language guidance.
- Line 122: Update agents/deploy/authenticated-sessions.mdx:122-122 to state
that backend session-creation requests must send the language setting as
overrides.language rather than top-level language. Update
agents/deploy/web-sdk.mdx:64-64 to qualify language as shorthand for agentId
mode and direct sessionToken callers to configure the language on the backend.
- Around line 146-155: Make the JSON override example self-contained by adding a
dynamic_variables.name value matching the {{name}} placeholder in
overrides.first_message, or remove the placeholder from first_message while
preserving the example’s intent.
In `@agents/deploy/public-agents.mdx`:
- Line 95: Update the public-path documentation sentence to distinguish unknown
override fields, which return 422, from recognized prompt-shaping overrides that
are unsupported for public sessions and return 400; keep language and voice_id
as the allowed overrides.
In `@api-reference/openapi.json`:
- Line 1888: Update every overrides_allowed enum in the OpenAPI schema to
include first_message_prompt, including the five occurrences identified near the
existing voice_id entries and the additional schema definition range. Preserve
all existing enum values and ensure AgentSessionOverridesPayload and related
schemas consistently allow-list this value.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 35e20cd7-a363-4167-8b7a-77e43d4b3cd0
📒 Files selected for processing (11)
agents/build/configuration.mdxagents/build/dynamic-variables.mdxagents/build/voice-language.mdxagents/deploy/authenticated-sessions.mdxagents/deploy/public-agents.mdxagents/deploy/react-sdk.mdxagents/deploy/web-sdk.mdxagents/deploy/widget.mdxagents/quickstart.mdxapi-reference/agent-errors.mdxapi-reference/openapi.json
| | `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). | |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Align all language guidance with the wire contract.
Top-level language is an SDK/widget shorthand for overrides.language. It is not a field in the backend session-creation payload, and it cannot modify a session that already exists behind sessionToken.
agents/deploy/authenticated-sessions.mdx#L122-L122: Update the request guidance so backend callers sendoverrides.language, not top-levellanguage.agents/deploy/web-sdk.mdx#L64-L64: Qualify thelanguageoption asagentId-mode shorthand and directsessionTokencallers to configure it on the backend.
📍 Affects 2 files
agents/deploy/authenticated-sessions.mdx#L122-L122(this comment)agents/deploy/web-sdk.mdx#L64-L64
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@agents/deploy/authenticated-sessions.mdx` at line 122, Update
agents/deploy/authenticated-sessions.mdx:122-122 to state that backend
session-creation requests must send the language setting as overrides.language
rather than top-level language. Update agents/deploy/web-sdk.mdx:64-64 to
qualify language as shorthand for agentId mode and direct sessionToken callers
to configure the language on the backend.
Source: Coding guidelines
| | `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`. | |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Document the voice_id length limit.
The OpenAPI schema limits overrides.voice_id to 256 characters. The table only states string. Add the limit so users can predict validation failures.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@agents/deploy/authenticated-sessions.mdx` at line 143, Update the voice_id
field description in the overrides table to document the 256-character maximum
enforced by the OpenAPI schema, while preserving the existing voice model and
language guidance.
Source: Coding guidelines
| ```json | ||
| { | ||
| "agent_id": "YOUR_AGENT_ID", | ||
| "overrides": { | ||
| "first_message": "Welcome back, {{name}} — picking up where we left off.", | ||
| "voice_id": "802e3bc2b27e49c2995d23ef70e6ac89", | ||
| "language": "ja" | ||
| } | ||
| } | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Make the override example self-contained.
The example sends {{name}} in first_message but provides no dynamic_variables.name. The documented behavior leaves unmatched placeholders as literal text.
Add a matching variable or remove the placeholder.
Proposed example update
"first_message": "Welcome back, {{name}} — picking up where we left off.",
"voice_id": "802e3bc2b27e49c2995d23ef70e6ac89",
"language": "ja"
- }
+ },
+ "dynamic_variables": { "name": "Ada" }
}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ```json | |
| { | |
| "agent_id": "YOUR_AGENT_ID", | |
| "overrides": { | |
| "first_message": "Welcome back, {{name}} — picking up where we left off.", | |
| "voice_id": "802e3bc2b27e49c2995d23ef70e6ac89", | |
| "language": "ja" | |
| } | |
| } | |
| ``` |
🧰 Tools
🪛 GitHub Check: Mintlify Validation (hanabiaiinc) - vale-spellcheck
[warning] 151-151: agents/deploy/authenticated-sessions.mdx#L151
Did you really mean 'voice_id'?
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@agents/deploy/authenticated-sessions.mdx` around lines 146 - 155, Make the
JSON override example self-contained by adding a dynamic_variables.name value
matching the {{name}} placeholder in overrides.first_message, or remove the
placeholder from first_message while preserving the example’s intent.
Source: Coding guidelines
| ## 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: |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Distinguish unknown fields from unsupported public overrides.
The sentence says that every override other than language and voice_id is rejected with 400. Unknown fields inside overrides are documented elsewhere as 422; 400 applies to recognized fields that are not allowed for the public session.
Limit the 400 statement to recognized prompt-shaping overrides.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@agents/deploy/public-agents.mdx` at line 95, Update the public-path
documentation sentence to distinguish unknown override fields, which return 422,
from recognized prompt-shaping overrides that are unsupported for public
sessions and return 400; keep language and voice_id as the allowed overrides.
Source: Coding guidelines
| "first_message", | ||
| "system_prompt", | ||
| "voice_profile_id", | ||
| "voice_id", |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Add first_message_prompt to every overrides_allowed enum.
AgentSessionOverridesPayload now defines first_message_prompt, and the schema states that every override must be allow-listed. The enums at Lines 1888, 2115, 2293, 10994, and 11817 still omit this value. Generated clients and schema validators cannot represent an agent that enables this override.
Add first_message_prompt to all five enums.
Proposed schema update
"first_message",
+"first_message_prompt",
"system_prompt",Also applies to: 2115-2115, 2293-2293, 10409-10421, 10994-10994, 11817-11817
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@api-reference/openapi.json` at line 1888, Update every overrides_allowed enum
in the OpenAPI schema to include first_message_prompt, including the five
occurrences identified near the existing voice_id entries and the additional
schema definition range. Preserve all existing enum values and ensure
AgentSessionOverridesPayload and related schemas consistently allow-list this
value.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 participant
What
## Overridessection — the single home for override semantics: the five-field table (first_message,first_message_prompt,system_prompt,voice_id,language) with types, limits, and what each replaces; example request; the public-session cap (language+voice_idonly); what is not an override (max_duration_secondscomes from conversation config).voice_profile_id→voice_idacross quickstart, configuration, voice-language, web-sdk, and openapi.json (six schemas synced surgically from the API).languageis documented as SDK-side sugar folded intooverrides.language— no longer a wire field.400behavior ("not enabled for the agent").Sequencing
Content describes platform-api#1264, merged — publish after it deploys.
Prettier clean;
mint broken-linksclean (temp/ and .mintlify skill leftovers are pre-existing).🤖 Generated with Claude Code