Added docs for warm-transfer-with-twiml

Author: ramsrib

fern/call-forwarding.mdx

@@ -220,6 +220,25 @@ In this mode, Vapi delivers a custom static message to the recipient before tran
 }
 ```
 
+#### 3. Warm Transfer with TwiML
+
+In this mode, Vapi executes TwiML instructions on the destination call leg before connecting the customer.
+
+* **Configuration:**
+   * Set the `mode` to `"warm-transfer-with-twiml"`.
+   * Provide the TwiML instructions in the `twiml` property.
+   * Supports only `Play`, `Say`, `Gather`, `Hangup`, and `Pause` verbs.
+   * Maximum TwiML length is 4096 characters.
+
+* **Example:**
+
+```json
+"transferPlan": {
+  "mode": "warm-transfer-with-twiml",
+  "twiml": "<Say>Hello, transferring a customer to you.</Say><Pause length=\"2\"/><Say>They called about billing questions.</Say>"
+}
+```
+
 #### Complete Example
 
 Here is a full example of a `transferCall` payload using the warm transfer with summary mode:
@@ -259,4 +278,30 @@ Here is a full example of a `transferCall` payload using the warm transfer with
 }
 ```
 
+Here is a full example of a `transferCall` payload using the warm transfer with TwiML mode:
+
+```json
+{
+  "type": "transferCall",
+  "messages": [
+    {
+      "type": "request-start",
+      "content": "I'll transfer you to someone who can help."
+    }
+  ],
+  "destinations": [
+    {
+      "type": "number",
+      "number": "+14155551234",
+      "description": "Transfer to customer support",
+      "transferPlan": {
+        "mode": "warm-transfer-with-twiml",
+        "twiml": "<Say>Hello, this is an incoming call from a customer.</Say><Pause length=\"1\"/><Say>They have questions about their recent order.</Say><Pause length=\"1\"/><Say>Connecting you now.</Say>",
+        "sipVerb": "refer"
+      }
+    }
+  ]
+}
+```
+
 **Note:** In all warm transfer modes, the `{{transcript}}` variable contains the full transcript of the call and can be used within the `summaryPlan`.