Skip to content

docs: add Model fallback configuration guide - #1309

Draft
stephenvapiai wants to merge 2 commits into
VapiAI:mainfrom
stephenvapiai:helpcenter-update/model-fallback-plan
Draft

stephenvapiai wants to merge 2 commits into
VapiAI:mainfrom
stephenvapiai:helpcenter-update/model-fallback-plan

Conversation

@stephenvapiai

Copy link
Copy Markdown
Contributor

What changed

Adds a new help center page, Model fallback configuration (fern/customization/model-fallback-plan.mdx), and wires it into fern/docs.yml under Documentation → Assistants → Model configurations, right after the existing Voice/Transcriber fallback pages.

Why (customer evidence)

Over the last 7 days, "Language Model Providers" was the top-volume Ask AI (docs.vapi.ai) topic (197 conversations this week vs. 127 the prior week vs. a ~131/week trailing-4-week baseline — an accelerating topic, not a one-off spike).

Most of that volume is customers successfully getting answers about which models each provider supports (OpenAI, Anthropic, Gemini, Groq, MiniMax, xAI, Mistral, etc.) — that content already exists and is accurate on the individual /providers/model/* pages, so it isn't the gap.

Within that same topic, a recurring cluster of distinct customers asked specifically about model-level fallback (fallbackModels / fallbackPlan on the model object) and the Ask AI assistant could not answer:

  • "what triggers a switch to the next model in a fallbackModels list on the model object" — outcome: refused
  • "about fallbackModels" — bot found no documentation for fallbackModels or fallbackPlan — outcome: refused

I verified against the live Create Assistant API reference that fallbackModels is a real, documented field — but only on OpenAIModel (list of fallback model IDs) and AnthropicBedrockModel (at most one same-provider fallback). No other provider schema exposes it. Meanwhile Vapi already ships dedicated guides for the analogous features on the other two pipeline components (voice-fallback-plan.mdx, customization/transcriber-fallback-plan.mdx) — there was no equivalent page for models, which is exactly the shape of confusion customers hit (they expected a fallbackPlan-style page like voice/transcriber have, and the assistant had nothing to cite).

This is a missing content gap, not a wording tweak: fallbackModels previously only appeared in changelog entries and a Simulations example, never in a standalone how-to guide.

Scope / what this intentionally does NOT claim

  • Does not claim cross-provider model fallback exists (unlike voice/transcriber) — the new page explicitly calls this out so it doesn't create a different kind of confusion.
  • Does not add Dashboard UI steps, since I could not confirm a Dashboard control for model-level fallback (voice/transcriber fallback pages document Dashboard steps I could verify; this one is API-only until confirmed otherwise).
  • Scoped to the two providers (OpenAIModel, AnthropicBedrockModel) that actually expose fallbackModels in the live API schema — verified directly against the Create Assistant API reference, not assumed.

Excluded candidates (per review scope)

Other candidate gaps touching security, auth/authorization, data privacy, or compliance topics (e.g. a customer support request for architecture/security/data-retention documentation, and the separate Compliance Plans taxonomy bucket) were intentionally skipped for this PR and not drafted, per the review's exclusion criteria for that category.

Checks done

  • Confirmed no recent commit or open PR already covers model fallback (list_commits on the two sibling fallback pages, search_code for fallbackModels, list_pull_requests).
  • Pinned the edit to the current main tip (d9efddec9207511d8e6c249fbdad82db30f89f35) and rechecked main hadn't moved immediately before branching.
  • Verified the fallbackModels schema (allowed values, per-provider availability) directly against /api-reference/assistants/create.

@stephenvapiai

Copy link
Copy Markdown
Contributor Author

Why this gap, and what was excluded

  • Source: Enterpret Context Graph, last 7 days (2026-10-05 to 2026-10-12) vs. prior 7 days vs. trailing 4-week baseline, across Zendesk-style support tickets, Discord, Ask AI (docs.vapi.ai) conversations, and NPS surveys.
  • "Language Model Providers" was the top-volume, accelerating topic this week (197 vs. 127 prior week vs. ~131/week baseline). Within it, a recurring cluster of distinct customers asked about model-level fallbackModels/fallbackPlan and the Ask AI assistant returned refused/silent — i.e. no documentation to cite. Verified against the live Create Assistant API reference that fallbackModels is real but undocumented outside changelog entries, and only on OpenAIModel + AnthropicBedrockModel.
  • Verified via list_commits (on voice-fallback-plan.mdx and transcriber-fallback-plan.mdx), search_code for fallbackModels, and list_pull_requests that no recent commit or open PR already covers this, to avoid duplicating in-flight work.
  • Excluded from this PR by review scope: other candidate gaps this week that touched security vulnerabilities, authentication/authorization risk, privacy/data exposure, regulatory obligations, or compliance claims — e.g. a customer support request for architecture/security/data-flow/data-retention documentation, and the separate Compliance Plans taxonomy bucket — were intentionally not drafted or opened as PRs under this review's exclusion criteria.
  • The diff is scoped to only the drafted content change: the new fern/customization/model-fallback-plan.mdx page and its single fern/docs.yml nav entry. No unrelated files were touched.

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