Skip to content

Document traffic splitting stickiness and the repeat caller opt-out - #1307

Draft
peter-vapi wants to merge 2 commits into
mainfrom
peter/DEPLOY-172-stickiness-opt-out-docs
Draft

peter-vapi wants to merge 2 commits into
mainfrom
peter/DEPLOY-172-stickiness-opt-out-docs

Conversation

@peter-vapi

Copy link
Copy Markdown
Contributor

Description

Hold until VapiAI/vapi#22742 deploys. This page documents repeatCallerStickiness, which only exists once that API change is live. The dashboard checkbox ships in VapiAI/vapi#22743. Tracked by DEPLOY-172, DEPLOY-176, and DEPLOY-187.

  • Replaces "sticky routing is best effort" with how stickiness actually works: the caller's identity hashes to one of 100,000 buckets, each version owns a contiguous range of buckets in the order the split lists them, and no caller-to-version assignment is ever stored.
  • Adds a worked table for a 90/10 → 50/50 → 100% ramp, showing which callers move at each step and why reordering versions moves many callers at once.
  • Adds a table of what counts as a caller identity (phone number, SIP username, web call, withheld number, saved customer id) and whether each one sticks.
  • Documents the opt-out. In the dashboard, clear the "Repeat caller stickiness" checkbox in the header traffic editor or in the publish Traffic step. Through the API, send repeatCallerStickiness: false. It defaults to true, and sending it with allocationIntent: "follow-latest" is rejected.
  • Adds an API example and two common situations: running an experiment, and testing both versions of a split from your own phone.

Testing Steps

  • Run the app locally using fern docs dev or navigate to preview deployment
  • Ensure that the changed pages and code snippets work
  • Confirm #how-stickiness-works resolves (the dashboard's "Learn more" link targets it)

Replace the "sticky routing is best effort" framing with the actual
deterministic mechanism: caller identity hashes to one of 100,000
buckets, targets own contiguous ranges in listed order, and nothing
is ever stored. This explains why ramping only moves callers forward
and why reordering targets re-deals ranges.

- Add a worked bucket-range table showing a 90/10 to 50/50 to 100%
  ramp and which callers move at each step
- Add an identity-class table (phone, SIP, web, withheld, saved
  customer id) with per-situation stickiness behavior and examples
- Document the new repeatCallerStickiness: false opt-out, including
  its default (true), its rejection when combined with
  allocationIntent: follow-latest, and an API example
- Add guidance for testing both arms of a split from one's own phone
  by disabling stickiness temporarily

Fixes DEPLOY-172

Must not merge before the repeatCallerStickiness API change deploys.

OpenCode session ID: ses_f108c3e24ffe0wHXs7DTqREQtW
- Add dashboard steps for clearing the "Repeat caller stickiness"
  checkbox in the traffic editor, reachable from the traffic pill or
  the Traffic step when publishing
- Note that the dashboard persists the setting across future splits
- Keep the existing API opt-out instructions (repeatCallerStickiness:
  false) as the alternative path, now clearly separated from the
  dashboard flow

Fixes DEPLOY-176

OpenCode session ID: ses_f108c3e24ffe0wHXs7DTqREQtW
@github-actions

github-actions Bot commented Oct 9, 2026

Copy link
Copy Markdown
Contributor

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant