docs: vendor-neutral session-token terminology in API reference - #401
docs: vendor-neutral session-token terminology in API reference#401abhishekmishragithub wants to merge 2 commits into
Conversation
Field and endpoint descriptions on POST /conversation/chat, /webcall, and /register-call now describe the returned artefacts as 'session access token' / 'session room ID' / 'WebSocket URL' rather than naming the underlying media platform vendor. Scope is prose only: no field renames, no behaviour change, no SDK regen needed. Response host examples (the actual URL customers connect to) stay as-is; those are the real hostnames a client sees. Two historical changelog entries and one Flutter page mention scrubbed for consistency.
|
crim doesn't review pull requests automatically here. Comment |
abhishekmishragithub
added
the
skip-changelog
|
crim review |
|
crim is reviewing this pull request. Findings will be posted shortly. |
![crim-app[bot]](https://avatars.githubusercontent.com/u/64185252?s=60&v=4){kind=small}
There was a problem hiding this comment.
Assessment
A clean docs-only change; safe to merge with one cosmetic inconsistency worth a glance.
What this PR does
Replaces vendor-specific "LiveKit" terminology with vendor-neutral wording ("session access token", "WebSocket host/URL", "third-party voice SDK") across the Atoms OpenAPI spec, a Flutter guide, and two changelog entries.
Findings
- Low:
fern/apis/atoms/openapi/openapi.yaml:11279— examplehostvalues still containlivekit.cloud, partially defeating the vendor-neutral goal.
Findings outside the diff
These concern lines GitHub won't allow inline comments on (unchanged or outside this PR's diff).
-
fern/apis/atoms/openapi/openapi.yaml:11279— Low: Examplehostvalues still expose the vendor domain after the vendor-neutral rename.The prose descriptions were changed to "WebSocket URL to connect to", but the example values at lines 11279, 11334, and 11570 remain
wss://atoms-prod-evcaw70g.livekit.cloud. If the intent is to hide the underlying provider, consider a neutral placeholder (e.g.wss://atoms-prod-evcaw70g.example-rtc.cloud). Not a functional issue, but it leaks exactly the name this PR set out to remove.
Good to mergeNicely thorough find-and-replace, though the sample URLs are still whispering "livekit.cloud" behind the vendor-neutral curtain. Approve. |
The prose descriptions were rewritten to "WebSocket URL" but the example values still exposed the LiveKit hostname across three locations, defeating the vendor-neutral goal of this PR. Replace wss://atoms-prod-evcaw70g.livekit.cloud with a neutral placeholder wss://rtc.example-provider.com in all three sites: - inline register-call response example (line 11279) - inline register-call outbound example (line 11334) - schema field example (line 11570) Customer-observable value: the real host they receive is unchanged. Only the docs example wording changes.
) The sibling SDK-generation override at fern/apis/waves/openapi/ get-voices-openapi-overrides.yaml was updated in #402 to match the base spec on the pool-scoped enum, but the description stopped short: the two markdown links (unified TTS route + get-all-models cross-link) were omitted from the override. The Waves spec drift CI check compares base vs sibling override, and this mismatch was failing every open PR that touched any waves spec file (#394, #401, #406, and any future spec edit). Copy the two link lines verbatim so the two files match token-for-token. Local run of scripts/spec-live-tests/spec_drift_check.py now reports PASS — no drift.
1 participant
Summary
Prose-only edit. Field and endpoint descriptions on the browser-session endpoints (
POST /conversation/chat,/webcall,/register-call) now use vendor-neutral terminology:session access token,session room ID,WebSocket URL to connect to, instead of naming the underlying media-platform vendor by brand in customer-facing docs.Response host examples (the real hostname the client connects to) stay as-is; that is a fact about our infrastructure that clients see regardless.
Scope
fern/apis/atoms/openapi/openapi.yaml— 10 prose replacements across three endpoint descriptions and their response field descriptions.fern/products/atoms/pages/intro/reference/changelog-entries/2026-08-08-account-webcall-campaign-endpoints.mdx— one bullet.fern/products/atoms/pages/intro/reference/changelog-entries/2026-04-24-mobile-voice-widgets.mdx— one sentence.fern/products/atoms/pages/dev/integrate/mobile/flutter.mdx— one line under "WebRTC-free".What is NOT changed
host:example values — those are the actual URLs customers see. Same principle as the SIP origination URL in PR docs(sip-trunking): transport contract + E.164 prefix + real troubleshooting #400.build-with-coding-agent.mdxmentions of LiveKit — those describe our SDK as a plugin ON LiveKit Agents (a third-party orchestrator we integrate with, alongside Pipecat). That is an integration-context reference, not naming our infra.Skip changelog
Applied
skip-changelogbecause this is a description-only edit — no behaviour, field name, or schema shape changed. The workflow's own message says description-only edits should use this label.Test plan
POST /conversation/register-callfield descriptions read "Session access token", "WebSocket URL to connect to", etc.