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. Create a Transfer Call Tool in the Dashboard

The recommended approach is to create your transfer call tool in the Vapi dashboard:

1. Navigate to Tools in your Vapi dashboard
2. Click Create Tool
3. Select Transfer Call as the tool type
4. Configure your destinations:
   • Department A: +1234567890 with message “I am forwarding your call to Department A. Please stay on the line.”
   • Department B: +0987654321 with message “I am forwarding your call to Department B. Please stay on the line.”
   • Department C: +1122334455 with message “I am forwarding your call to Department C. Please stay on the line.”

2. Alternative: API Configuration

You can also define the tool via API with destinations and corresponding messages:

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
    ]

3. 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
}

4. 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": "+918936850523",
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
}

6. Experimental Warm Transfer

In this mode, Vapi dials the destination number and places the caller on hold (with a default ringtone). If the destination answers, Vapi connects the calls. If voicemail is detected or the call isn’t answered, Vapi plays a fallback message to the caller.

• Configuration:

  • Set the mode to "warm-transfer-experimental".
  • Provide a message to be spoken to the operator when they answer.
  • Optionally define a summaryPlan that will take precedence over the message if enabled.
  • Configure a fallbackPlan with a message and whether to end the call if transfer fails.
  • Optionally provide a holdAudioUrl to play custom hold music to the customer during the transfer.
  • Configure voicemailDetectionType to customize how human voice detection is performed (only applies when the provider is Google or OpenAI):
    • "audio" (default): Supports a wide range of machine detection including beep detection and other audio cues
    • "transcript": Uses transcript-based detection with the lowest latency and faster transfer processing times
  • Note that only Google or OpenAI providers are supported for voicemail detection with transfer plans, even if the assistant configuration supports other providers like Twilio or Vapi.

• Example:

1
"transferPlan": {
2
  "mode": "warm-transfer-experimental",
3
  "message": "Transferring a customer to you.",
4
  "holdAudioUrl": "https://api.twilio.com/cowbell.mp3",
5
  "voicemailDetectionType": "transcript",
6
  "fallbackPlan": {
7
    "message": "Could not transfer your call, goodbye.",
8
    "endCallEnabled": true
9
  },
10
  "summaryPlan": {
11
    "enabled": true,
12
    "messages": [
13
      {
14
        "role": "system",
15
        "content": "Please provide a summary of the call."
16
      },
17
      {
18
        "role": "user",
19
        "content": "Here is the transcript:\n\n{{transcript}}\n\n"
20
      }
21
    ]
22
  }
23
}

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

1
{
2
  "type": "transferCall",
3
  "function": {
4
    "name": "myTransferCall"
5
  },
6
  "destinations": [
7
    {
8
      "type": "number",
9
      "number": "+1123456789",
10
      "message": "Transferring the call now...",
11
      "transferPlan": {
12
        "mode": "warm-transfer-experimental",
13
        "message": "Transferring a customer to you.",
14
        "holdAudioUrl": "https://assets.example.com/music.mp3",
15
        "voicemailDetectionType": "audio",
16
        "fallbackPlan": {
17
          "message": "Could not transfer your call, goodbye.",
18
          "endCallEnabled": true
19
        },
20
        "summaryPlan": {
21
          "enabled": true,
22
          "messages": [
23
            {
24
              "role": "system",
25
              "content": "Please provide a summary of the call."
26
            },
27
            {
28
              "role": "user",
29
              "content": "Here is the transcript:\n\n{{transcript}}\n\n"
30
            }
31
          ]
32
        }
33
      }
34
    }
35
  ]
36
}

7. Assistant-Based Warm Transfer (Experimental)

For use cases requiring AI-managed transfers, Vapi supports using assistants to handle the transfer process. This allows the assistant to converse with operators and make transfer decisions based on your configuration.

Notes:

• In all warm transfer modes, the {{transcript}} variable contains the full transcript of the call and can be used within the summaryPlan.
• The holdAudioUrl property (available only in warm-transfer-experimental mode) allows you to specify a custom MP3 file URL that will be played to the customer while they are on hold during the transfer. If not provided, the default hold audio will be used.
• The voicemailDetectionType parameter allows you to optimize the detection method based on your needs:
  • Use "transcript" for the fastest transfer processing with lowest latency
  • Use "audio" (default) for comprehensive machine detection including beep detection and other audio cues
• For more details about transfer plans and configuration options, please refer to the transferCall API documentation