DeployCalls

Call Forwarding

Vapi’s call forwarding functionality allows you to redirect calls to different phone numbers based on specific conditions using tools. This guide explains how to set up and use the transferCall function for call forwarding.

Key Concepts

Call Forwarding Tools

  • transferCall Tool: This tool enables call forwarding to predefined phone numbers with specific messages based on the destination.

Parameters and Messages

  • Destinations: A list of phone numbers where the call can be forwarded.
  • Messages: Custom messages that inform the caller about the call being forwarded.

Setting Up Call Forwarding

1. Defining Destinations and Messages

The transferCall tool includes a list of destinations and corresponding messages to notify the caller:

1{
2  "tools": [
3    {
4      "type": "transferCall",
5      "destinations": [
6        {
7          "type": "number",
8          "number": "+1234567890",
9          "message": "I am forwarding your call to Department A. Please stay on the line."
10        },
11        {
12          "type": "number",
13          "number": "+0987654321",
14          "message": "I am forwarding your call to Department B. Please stay on the line."
15        },
16        {
17          "type": "number",
18          "number": "+1122334455",
19          "message": "I am forwarding your call to Department C. Please stay on the line."
20        }
21      ],
22      "function": {
23        "name": "transferCall",
24        "description": "Use this function to transfer the call. Only use it when following instructions that explicitly ask you to use the transferCall function. DO NOT call this function unless you are instructed to do so.",
25        "parameters": {
26          "type": "object",
27          "properties": {
28            "destination": {
29              "type": "string",
30              "enum": ["+1234567890", "+0987654321", "+1122334455"],
31              "description": "The destination to transfer the call to."
32            }
33          },
34          "required": ["destination"]
35        }
36      },
37      "messages": [
38        {
39          "type": "request-start",
40          "content": "I am forwarding your call to Department A. Please stay on the line.",
41          "conditions": [
42            {
43              "param": "destination",
44              "operator": "eq",
45              "value": "+1234567890"
46            }
47          ]
48        },
49        {
50          "type": "request-start",
51          "content": "I am forwarding your call to Department B. Please stay on the line.",
52          "conditions": [
53            {
54              "param": "destination",
55              "operator": "eq",
56              "value": "+0987654321"
57            }
58          ]
59        },
60        {
61          "type": "request-start",
62          "content": "I am forwarding your call to Department C. Please stay on the line.",
63          "conditions": [
64            {
65              "param": "destination",
66              "operator": "eq",
67              "value": "+1122334455"
68            }
69          ]
70        }
71      ]
72    }
73  ]
74}

You can also specify the extension parameter to forward the call to an extension.

1    "destinations": [
2        {
3            "type": "number",
4            "number": "+1234567890",
5            "extension": "4603",
6            "message": "I am forwarding your call to Department A. Please stay on the line."
7        }
8    ]

2. Using the transferCall Function

When the assistant needs to forward a call, it uses the transferCall function with the appropriate destination:

1{
2  "function": {
3    "name": "transferCall",
4    "parameters": {
5      "destination": "+1234567890"
6    }
7  }
8}

3. Customizing Messages

Customize the messages for each destination to provide clear information to the caller:

1{
2  "messages": [
3    {
4      "type": "request-start",
5      "content": "I am forwarding your call to Department A. Please stay on the line.",
6      "conditions": [
7        {
8          "param": "destination",
9          "operator": "eq",
10          "value": "+1234567890"
11        }
12      ]
13    }
14  ]
15}

Instructing the Assistant

Use the system prompt to guide the assistant on when to utilize each forwarding number. For example:

  • “If the user asks for sales, call the transferCall function with +1234567890.”
  • “If the user requests technical support, use the transferCall function with +0987654321.”

Troubleshooting

  • If calls are not being transferred, check the logs for errors.
  • Ensure that the correct destination numbers are used.
  • Ensure you have written the function description properly to indicate where you want to forward the call
  • Test the call forwarding setup thoroughly to confirm its functionality.

Call Transfers Mode

Vapi supports two types of call transfers:

  1. Blind Transfer (default): Directly transfers the call to another agent without providing any prior information to the recipient.
  2. Warm Transfer: Transfers the call to another agent after providing context about the call. The context can be either a full transcript or a summary, based on your configuration.

Warm Transfer

To implement a warm transfer, add a transferPlan object to the transferCall tool syntax and specify the transfer mode.

Modes of Warm Transfer

1. Warm Transfer with Summary

In this mode, Vapi provides a summary of the call to the recipient before transferring.

  • Configuration:

    • Set the mode to "warm-transfer-with-summary".
    • Define a summaryPlan specifying how the summary should be generated.
    • Use the {{transcript}} variable to include the call transcript.

  • Example:

1"transferPlan": {
2  "mode": "warm-transfer-with-summary",
3  "summaryPlan": {
4    "enabled": true,
5    "messages": [
6      {
7        "role": "system",
8        "content": "Please provide a summary of the call."
9      },
10      {
11        "role": "user",
12        "content": "Here is the transcript:\n\n{{transcript}}\n\n"
13      }
14    ]
15  }
16}

2. Warm Transfer with Message

In this mode, Vapi delivers a custom message to the recipient before transferring the call.

  • Configuration:

    • Set the mode to "warm-transfer-with-message".
    • Provide the custom message in the message property.
    • Note that the {{transcript}} variable is not available in this mode.

  • Example:

1"transferPlan": {
2  "mode": "warm-transfer-with-message",
3  "message": "Hey, this call has been forwarded through Vapi."
4}

Complete Example

Here is a full example of a transferCall payload using the warm transfer with summary mode:

1{
2  "type": "transferCall",
3  "messages": [
4    {
5      "type": "request-start",
6      "content": "I'll transfer you to someone who can help."
7    }
8  ],
9  "destinations": [
10    {
11      "type": "number",
12      "number": "+918936850777",
13      "description": "Transfer the call",
14      "transferPlan": {
15        "mode": "warm-transfer-with-summary",
16        "summaryPlan": {
17          "enabled": true,
18          "messages": [
19            {
20              "role": "system",
21              "content": "Please provide a summary of the call."
22            },
23            {
24              "role": "user",
25              "content": "Here is the transcript:\n\n{{transcript}}\n\n"
26            }
27          ]
28        }
29      }
30    }
31  ]
32}

3. Warm Transfer with Wait and Say Message

In this mode, Vapi waits for the recipient to speak first and then delivers a custom message to the recipient before transferring the call.

  • Configuration:

    • Set the mode to "warm-transfer-wait-for-operator-to-speak-first-and-then-say-message".
    • Provide the custom message in the message property.
    • Note that the {{transcript}} variable is not available in this mode.

  • Example:

1"transferPlan": {
2  "mode": "warm-transfer-wait-for-operator-to-speak-first-and-then-say-message",
3  "message": "Hey, this call has been forwarded through Vapi."
4}

4. Warm Transfer with Wait and Say Summary

In this mode, Vapi waits for the recipient to speak first and then delivers a summary of the call to the recipient before transferring the call.

  • Configuration:

    • Set the mode to "warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary".
    • Define a summaryPlan specifying how the summary should be generated.
    • Use the {{transcript}} variable to include the call transcript.

  • Example:

1"transferPlan": {
2  "mode": "warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary",
3  "summaryPlan": {
4    "enabled": true,
5    "messages": [
6      {
7        "role": "system",
8        "content": "Please provide a summary of the call."
9      },
10      {
11        "role": "user",
12        "content": "Here is the transcript:\n\n{{transcript}}\n\n"
13      }
14    ]
15  }
16}

5. Warm Transfer with TwiML

In this mode, Vapi executes TwiML instructions on the destination call leg before connecting the destination number.

  • Configuration:

    • Set the mode to "warm-transfer-with-twiml".
    • Provide the TwiML instructions in the twiml property.
    • Supports only Play, Say, Gather, and Pause verbs.
    • Maximum TwiML length is 4096 characters.
    • TwiML must be provided as a single-line string without line breaks or tabs, and must be a valid XML string. For example: <Say>Hello</Say> is valid, but <Say>Hello\n</Say> is not.

  • Example:

1"transferPlan": {
2  "mode": "warm-transfer-with-twiml",
3  "twiml": "<Say>Hello, transferring a customer to you.</Say><Pause length=\"2\"/><Say>They called about billing questions.</Say>"
4}

Here is a full example of a transferCall payload using the warm transfer with TwiML mode:

1{
2  "type": "transferCall",
3  "messages": [
4    {
5      "type": "request-start",
6      "content": "I'll transfer you to someone who can help."
7    }
8  ],
9  "destinations": [
10    {
11      "type": "number",
12      "number": "+14155551234",
13      "description": "Transfer to customer support",
14      "transferPlan": {
15        "mode": "warm-transfer-with-twiml",
16        "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>",
17        "sipVerb": "refer"
18      }
19    }
20  ]
21}

Notes:

  • In all warm transfer modes, the {{transcript}} variable contains the full transcript of the call and can be used within the summaryPlan.
  • For more details about transfer plans and configuration options, please refer to the transferCall API documentation