docs: clarify transfer event coverage and initiation semantics

[dhruva-vapi]

Description

Problem: The server-events guide says transfer-update fires for every transfer, so customers can wait for a webhook that phone and SIP warm transfers never emit.

This corrects the documented event coverage and explains which signal customers can use today.

• Update fern/server-url/events.mdx with the legacy assistant-destination behavior, valid nested payload excerpts, and the status-update / forwarding signal for Vapi-managed phone and SIP transfers. Forwarding means initiation; it does not confirm an answer or successful handoff. Explain the Server URL and subscription requirements.
• Add a concise clarification and cross-reference in fern/calls/assistant-based-warm-transfer.mdx, including that temporary transfer-assistant activation/restoration does not emit transfer-update.
• No navigation or runtime changes.

Verified against Vapi main b84bc498e8525679cefab8b9552e891d32b1909e: voice-call emitter, phone/SIP forwarding and transport, transfer-assistant activation, and restoration. The broader message schema does not establish ringing/success/failure lifecycle events.

Open question for Steve: Should a future runtime change extend transfer-update, or use a separate event for actual started/connected/failed/canceled outcomes? Those are proposed semantics, not an existing contract, and are outside this docs-only PR.

Testing Steps

• Pinned Fern validation: zero errors, 14 existing warnings (11 API path conflicts, 2 theme contrast warnings, 1 unauthenticated redirect check skipped).
• Both added/changed JSON examples parse strictly and retain the HTTP message envelope. Fourteen unrelated existing placeholder snippets on the events page remain unchanged.
• Added internal links and the transfer-update anchor resolve to existing pages/headings.
• git diff --check passes; source facts and customer wording reviewed. No TS/JS changes.
• Hosted preview build and Fern CI pass. Both changed pages verified through fetched rendered HTML (scripts excluded): corrected text, links, anchor, and valid nested payload examples. Preview. The preview build reports an existing TypeScript SDK snippet upload warning for @vapi/server-sdk; the changed pages render successfully.

[lightsage-app]

Lightsage docs evals

Lightsage could not queue docs evals for this PR.

Docs URL: https://vapi-preview-01a1553c-ae48-712a-a420-1c47680b3bde.docs.buildwithfern.com
Commit: f3870be
Reason: No evals are selected for GitHub PR evals. Open Lightsage and enable the GitHub checkbox for at least one eval.

[dhruva-vapi]

• docs: clarify transfer event coverage and initiation semantics #1335 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

🌿 Preview your docs: https://vapi-preview-01a1423b-73d4-726b-b05b-94f1b56d0b86.docs.buildwithfern.com

[github-actions]

🌿 Preview your docs: https://vapi-preview-01a14593-be9d-70b9-91d9-e22319e57a5d.docs.buildwithfern.com

[stephenvapiai]

A few wording suggestions.

[github-actions]

🌿 Preview your docs: https://vapi-preview-01a1553c-53ca-709e-8732-e0a26c074fa5.docs.buildwithfern.com

[github-actions]

🌿 Preview your docs: https://vapi-preview-01a1553c-8a43-77ea-a17e-604260b74a2c.docs.buildwithfern.com

[github-actions]

🌿 Preview your docs: https://vapi-preview-01a1553c-caed-75fd-939e-539354b2ebbe.docs.buildwithfern.com

[github-actions]

🌿 Preview your docs: https://vapi-preview-01a1553c-ae48-712a-a420-1c47680b3bde.docs.buildwithfern.com