Add narrative traffic-splitting docs (assistants/versioning) - #1253
peter-vapi wants to merge 7 commits into
Conversation
|
🌿 Preview your docs: https://vapi-preview-01a0d0ae-c51c-75f9-ac91-5951b212b2b6.docs.buildwithfern.com |
- Introduce assistants/versioning/traffic-splitting.mdx covering the theory behind splitting live call traffic across published versions - Document canary releases, experiments, staged parking at 0%, and the follow-latest default so readers understand when explicit splits pin traffic versus reverting automatically - Walk through the three publish-flow choices (100%, split, 0%) and common rollout situations: finishing a canary, rolling back, urgent fixes mid-rollout, and fair comparisons - Include a POST /traffic-allocations API example and link to GET /traffic-allocations/latest for reading the governing split - Content is intentionally theory-oriented per DEPLOY-164; no step-by-step dashboard instructions are included - Register the new page in fern/docs.yml under the versioning section OpenCode session ID: ses_f39e30a81ffeNHfgqDyd9QqtbE
39d7a46 to
33e25f7
Compare
- Add a Note callout stating traffic splitting is in beta and requires Vapi to enable it for the org, with a support contact for access requests - Add availability: beta to the nav entry in docs.yml so the sidebar shows the beta badge, matching the GPT-Live pattern OpenCode session ID: ses_f976655e8ffeu5QUgO73DCP9iH
Lightsage docs evalsResult: completed with failures Average score: 67/100
|
|
🌿 Preview your docs: https://vapi-preview-01a0ea32-6178-7609-ac02-14aeb0f9998f.docs.buildwithfern.com |
| --- | ||
|
|
||
| <Note> | ||
| **Beta.** Traffic splitting must be enabled for your Vapi organization. Contact [support](mailto:support@vapi.ai) to request access. |
There was a problem hiding this comment.
What if we made this a google form to get responses and ask them things like "why do you want it"
There was a problem hiding this comment.
I love this, is it appropriate to ask for their org ID? How do we have customers self-identify? Email theoretically could map to multiple orgs, but we could just enable for all in those cases I guess. Also, is there precedent for Google Forms like this/a template you know of/account I should make it from?
There was a problem hiding this comment.
I think org ID is a good idea! I'm sure bets will have a better answer but we have created google forms in the past and I'm sure it's fine to do it again - we can make one and run it by product if there's more info they want to capture
| "assistantId": "9d5f9d3a-...", | ||
| "allocationIntent": "explicit", | ||
| "targets": [ | ||
| { "assistantVersionId": "b7e2c1d0-...", "percentage": 90 }, |
There was a problem hiding this comment.
Update with the new controller DTO when ready
- Reference published versions by label (e.g. "v7") instead of assistantVersionId, matching how version routes already work - Rename reason to description in the request body - Drop explicit allocationIntent for splits; it's inferred from the presence of targets, so posting targets alone starts or adjusts a canary while follow-latest stays the one explicit intent needed to stop a rollout - Add start/adjust/stop worked examples plus expectedCurrentAllocationId guidance for optimistic concurrency, and document GET history endpoint alongside the existing latest-allocation read OpenCode session ID: ses_f976655e8ffeu5QUgO73DCP9iH
|
🌿 Preview your docs: https://vapi-preview-01a0ea91-acb9-7769-b63b-068f672ead94.docs.buildwithfern.com |
Expand the beta callout on the traffic splitting doc to spell out what's included and excluded: - Included: percentage splits, sticky routing, dashboard editor, API with allocation change history - Excluded: per-version call metrics, side-by-side comparisons, and a dashboard view of past splits - Point users to the `assistantVersion` field on calls as the current workaround for comparing versions OpenCode session ID: ses_f976655e8ffeu5QUgO73DCP9iH
|
🌿 Preview your docs: https://vapi-preview-01a0eaae-15ca-721f-a7d3-a72437d337ed.docs.buildwithfern.com |
- Traffic splitting beta access now goes through a Google Form instead of emailing support@vapi.ai - Streamlines intake for the beta program OpenCode session ID: ses_f976655e8ffeu5QUgO73DCP9iH
- Replaced the long Google Forms URL with the forms.gle short link - Keeps the docs link shorter and easier to read/maintain OpenCode session ID: ses_f976655e8ffeu5QUgO73DCP9iH
|
🌿 Preview your docs: https://vapi-preview-01a0eab8-cd4f-7649-ab52-5d39f431a538.docs.buildwithfern.com |
|
🌿 Preview your docs: https://vapi-preview-01a0eab9-f2c4-7233-8507-34158086a038.docs.buildwithfern.com |
- Add a "Sticky routing is best effort" section explaining that stickiness is keyed on phone number or SIP username, so web calls, withheld caller IDs, and non-phone-number identifiers route independently each time. - Note that stickiness also depends on target order, so reordering versions in a split can move repeat callers to a different version. - Document the API validation rule: a split is only accepted when every version is listed once and percentages total exactly 100 with at least one above 0, otherwise the request returns a 400. OpenCode session ID: ses_f976655e8ffeu5QUgO73DCP9iH
|
🌿 Preview your docs: https://vapi-preview-01a0eabf-d36c-73ad-9895-8eb29ad2c4bd.docs.buildwithfern.com |
2 participants
What
New docs page
assistants/versioning/traffic-splitting.mdxplus its nav entry, landing spot for the dashboard'sVapiDocsLink.TRAFFIC_SPLITTINGlink from both split-editor surfaces.Editorial direction
Deliberately theory-oriented narrative (DEPLOY-164): why you'd split traffic (canary releases, experiments, staged parking at 0%), how routing works (new-calls-only, repeat-caller affinity, 0.001% granularity, 5-version cap), follow-latest vs pinned splits, the three publish-flow choices, and common rollout situations. No procedural step-by-step, so the page doesn't drift from UI micro-decisions. Screenshots follow once the UI settles (
fern/static/images/assistants/traffic-splitting/).Linear
DEPLOY-164 (child of DEPLOY-68). Feature ships behind
enable-traffic-splitting.