From 9a675cfa0daea33c785064f0ddf16c7530b177af Mon Sep 17 00:00:00 2001
From: Arthur Chi <arthurchi93@gmail.com>
Date: Tue, 23 Sep 2025 13:46:34 -0700
Subject: [PATCH] dynamic handoff custom error and live call control handoff
 examples

---
 fern/calls/call-features.mdx | 24 ++++++++++++++++++++++++
 fern/tools/handoff.mdx       |  7 +++++++
 2 files changed, 31 insertions(+)

diff --git a/fern/calls/call-features.mdx b/fern/calls/call-features.mdx
index 7bc202d07..72fa5b1ee 100644
--- a/fern/calls/call-features.mdx
+++ b/fern/calls/call-features.mdx
@@ -129,6 +129,30 @@ curl -X POST 'https://aws-us-west-2-production1-phone-call-websocket.vapi.ai/742
 }'
 ```
 
+### 6. Handoff Call
+Handoff the call to a different assistant.
+
+```bash
+curl -X POST 'https://aws-us-west-2-production1-phone-call-websocket.vapi.ai/7420f27a-30fd-4f49-a995-5549ae7cc00d/control' 
+-H 'content-type: application/json' 
+--data-raw '{
+  "type": "handoff",
+  "destination": {
+    "type": "assistant",
+    "contextEngineeringPlan": "none",
+    "assistant": {
+        "name": "new_assistant",
+        "voice": {
+            "provider": "vapi",
+            "voiceId": "Neha"
+        },
+    }                                    
+  },
+  "content": "Handing off your call now"
+}'
+```
+
+
 ## Call Listen Feature
 
 The `listenUrl` allows you to connect to a WebSocket and stream the audio data in real-time. You can either process the audio directly or save the binary data to analyze or replay later.
diff --git a/fern/tools/handoff.mdx b/fern/tools/handoff.mdx
index 1beb9c85e..7300b341f 100644
--- a/fern/tools/handoff.mdx
+++ b/fern/tools/handoff.mdx
@@ -226,6 +226,13 @@ destination: {
 },
 ```
 
+If the handoff should not executed, either respond with an empty destination, or provide a custom error. The custom error will be added to the message history.
+```json
+{
+  error: "Example custom error message"
+}
+````
+
 ### 3.2 Dynamic Handoff with Custom Parameters
 
 Pass additional context to your webhook for intelligent routing: