docs: clarify transfer event coverage and initiation semantics

fern/calls/assistant-based-warm-transfer.mdx

@@ -189,6 +189,10 @@ Place a test call and trigger the transfer. Confirm that:
 
 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.
+</Note>
+
 ## Troubleshooting
 
 | Symptom | Likely cause | Resolution |

fern/server-url/events.mdx

@@ -427,17 +427,47 @@ Respond with a destination and optionally a message:
 
 ### 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.
+
+Example payload excerpt for an assistant destination:
 
 ```json
 {
   "message": {
     "type": "transfer-update",
-    "destination": { /* assistant | number | sip */ }
+    "destination": {
+      "type": "assistant",
+      "assistantName": "Support"
+    },
+    "fromAssistant": { "name": "Receptionist" },
+    "toAssistant": { "name": "Support" }
   }
 }
 ```
 
+#### 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.
+
+Example payload excerpt for a phone destination:
+
+```json
+{
+  "message": {
+    "type": "status-update",
+    "status": "forwarding",
+    "destination": {
+      "type": "number",
+      "number": "+14155550100"
+    }
+  }
+}
+```
+
+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.
+
 ### User Interrupted
 
 Sent when the user interrupts the assistant. The optional `turnId` identifies the LLM turn that was interrupted, matching the `turnId` on `model-output` messages so you can discard that turn's tokens.