Repository navigation
docs: clarify transfer event coverage and initiation semantics - #1335
Open
dhruva-vapi wants to merge 2 commits into
Open
dhruva-vapi wants to merge 2 commits into
dhruva-vapi wants to merge 2 commits into
Conversation
Lightsage docs evalsLightsage could not queue docs evals for this PR. Docs URL: https://vapi-preview-01a14593-be9d-70b9-91d9-e22319e57a5d.docs.buildwithfern.com |
Contributor
|
🌿 Preview your docs: https://vapi-preview-01a1423b-73d4-726b-b05b-94f1b56d0b86.docs.buildwithfern.com |
Contributor
|
🌿 Preview your docs: https://vapi-preview-01a14593-be9d-70b9-91d9-e22319e57a5d.docs.buildwithfern.com |
stephenvapiai
left a comment
stephenvapiai
left a comment
Contributor
There was a problem hiding this comment.
A few wording suggestions.
| ### Transfer Update | ||
|
|
||
| Fires whenever a transfer occurs. | ||
| For voice calls, `transfer-update` is emitted by the legacy `transferCall` path when transferring to an assistant destination. It includes `destination`, `fromAssistant`, and `toAssistant`. It is not emitted for every assistant handoff or phone/SIP transfer, and it does not report ringing, connection, or transfer failure. |
Contributor
There was a problem hiding this comment.
Uses "sent" to match the rest of this page, and makes the list parallel so "every" applies to each item.
Suggested change
| For voice calls, `transfer-update` is emitted by the legacy `transferCall` path when transferring to an assistant destination. It includes `destination`, `fromAssistant`, and `toAssistant`. It is not emitted for every assistant handoff or phone/SIP transfer, and it does not report ringing, connection, or transfer failure. | |
| For voice calls, `transfer-update` is sent by the legacy `transferCall` path when transferring to an assistant destination. It includes `destination`, `fromAssistant`, and `toAssistant`. It is not sent for every assistant handoff, phone transfer, or SIP transfer, and it does not report ringing, connection, or transfer failure. |
|
|
||
| #### Phone and SIP transfers | ||
|
|
||
| Vapi-managed phone and SIP transfers, including [assistant-based warm transfers](/calls/assistant-based-warm-transfer) (`warm-transfer-experimental`), send a `status-update` with `status: "forwarding"` when the transfer is initiated. This event is sent before the transfer is attempted; it does not confirm that the destination rang, answered, or accepted the caller. |
Contributor
There was a problem hiding this comment.
Keeps the subject and verb together, and uses "starts" instead of "is initiated".
Suggested change
| Vapi-managed phone and SIP transfers, including [assistant-based warm transfers](/calls/assistant-based-warm-transfer) (`warm-transfer-experimental`), send a `status-update` with `status: "forwarding"` when the transfer is initiated. This event is sent before the transfer is attempted; it does not confirm that the destination rang, answered, or accepted the caller. | |
| Vapi-managed phone and SIP transfers send a `status-update` with `status: "forwarding"` when the transfer starts. This includes [assistant-based warm transfers](/calls/assistant-based-warm-transfer) (`warm-transfer-experimental`). This event is sent before the transfer is attempted; it does not confirm that the destination rang, answered, or accepted the caller. |
|
|
||
| The forwarding payload also includes `messages`, `messagesOpenAIFormatted`, `transcript`, and an optional `summary`. The deprecated `forwardingPhoneNumber` field contains the destination number or SIP URI; use `destination` instead. | ||
|
|
||
| To receive these events, configure a [Server URL](/server-url/setting-server-urls) and include the event type in `assistant.serverMessages`. `status-update` is included by default; `transfer-update` is not. Adding `transfer-update` to the subscription does not make phone/SIP transfers emit it. Use [call logs](/observability/logs/call-logs) and your telephony provider's call records to investigate the transfer outcome. |
Contributor
There was a problem hiding this comment.
Keeps the outcome guidance with the phone and SIP section, and moves the subscription rules (which cover both events) under their own heading. Also uses "send" and "phone or SIP" for consistency.
Suggested change
| To receive these events, configure a [Server URL](/server-url/setting-server-urls) and include the event type in `assistant.serverMessages`. `status-update` is included by default; `transfer-update` is not. Adding `transfer-update` to the subscription does not make phone/SIP transfers emit it. Use [call logs](/observability/logs/call-logs) and your telephony provider's call records to investigate the transfer outcome. | |
| Use [call logs](/observability/logs/call-logs) and your telephony provider's call records to investigate the transfer outcome. | |
| #### Subscribe to transfer events | |
| To receive these events, configure a [Server URL](/server-url/setting-server-urls) and include the event type in `assistant.serverMessages`. `status-update` is included by default; `transfer-update` is not. Adding `transfer-update` to the subscription does not make phone or SIP transfers send it. |
| In [**Logs → Calls**](/observability/logs/call-logs), inspect the original call, destination call leg, transcript, and ended reason. To retrieve these details through the API, see the [Get Call API reference](/api-reference/calls/get). An `assistant-forwarded-call` ended reason confirms that the transfer was initiated; it does not confirm that the destination answered. | ||
|
|
||
| <Note> | ||
| Assistant-based warm transfers to phone or SIP destinations do not emit `transfer-update`. The `status-update` event with `status: "forwarding"` signals transfer initiation, not a successful handoff. Switching to the transfer assistant and restoring the original assistant do not emit `transfer-update` either. See [transfer event behavior](/server-url/events#transfer-update) for payloads and subscription requirements. |
Contributor
There was a problem hiding this comment.
Shortens the callout by merging the two transfer-update sentences, and uses "send" to match the events page.
Suggested change
| Assistant-based warm transfers to phone or SIP destinations do not emit `transfer-update`. The `status-update` event with `status: "forwarding"` signals transfer initiation, not a successful handoff. Switching to the transfer assistant and restoring the original assistant do not emit `transfer-update` either. See [transfer event behavior](/server-url/events#transfer-update) for payloads and subscription requirements. | |
| Assistant-based warm transfers to phone or SIP destinations do not send `transfer-update`, including when the call switches to the transfer assistant and back. A `status-update` event with `status: "forwarding"` signals that the transfer started, not that it succeeded. See [transfer event behavior](/server-url/events#transfer-update) for payloads and subscription requirements. |
stephenvapiai
approved these changes
Oct 16, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Problem: The server-events guide says
transfer-updatefires 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.
fern/server-url/events.mdxwith the legacy assistant-destination behavior, valid nested payload excerpts, and thestatus-update/forwardingsignal 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.fern/calls/assistant-based-warm-transfer.mdx, including that temporary transfer-assistant activation/restoration does not emittransfer-update.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
messageenvelope. Fourteen unrelated existing placeholder snippets on the events page remain unchanged.transfer-updateanchor resolve to existing pages/headings.git diff --checkpasses; source facts and customer wording reviewed. No TS/JS changes.@vapi/server-sdk; the changed pages render successfully.