AssistantsTools

Default Tools

Adding Transfer Call, End Call, Dial Keypad, and API Request capabilities to your assistants.

Vapi voice assistants are given additional functions: transferCall, endCall, sms, dtmf (to dial a keypad with DTMF), and apiRequest. These functions can be used to transfer calls, hang up calls, send SMS messages, enter digits on the keypad, and integrate business logic with your existing APIs.

To add Default Tools to your agent, you need to add them in the tools array of your assistant. You can do this in your api request, or by creating a new tool in the dashboard tools page, and assigning it to your assistant.

Transfer Call

This function is provided when transferCall is included in the assistant’s list of available tools (see configuration options here). This function can be used to transfer the call to any of the destinations defined in the tool configuration (see details on destination options here).

1{
2  "model": {
3    "provider": "openai",
4    "model": "gpt-4o",
5    "messages": [
6      {
7        "role": "system",
8        "content": "You are an assistant at a law firm. When the user asks to be transferred, use the transferCall function."
9      }
10    ],
11    "tools": [
12      {
13          "type": "transferCall",
14          "destinations" : {
15            {
16              "type": "number",
17              "number": "+16054440129"
18            }
19          }
20      }
21    ]
22  }
23}

End Call

This function is provided when endCall is included in the assistant’s list of available tools (see configuration options here). The assistant can use this function to end the call.

1{
2  "model": {
3    "provider": "openai",
4    "model": "gpt-4o",
5    "messages": [
6      {
7        "role": "system",
8        "content": "You are an assistant at a law firm. If the user is being mean, use the endCall function."
9      }
10    ],
11    "tools": [
12      {
13          "type": "endCall"
14      }
15    ]
16  }
17}

Send Text

This function is provided when sms is included in the assistant’s list of available tool (see configuration options here). The assistant can use this function to send SMS messages using a configured Twilio account.

1{
2  "model": {
3    "provider": "openai",
4    "model": "gpt-4o",
5    "messages": [
6      {
7        "role": "system",
8        "content": "You are an assistant. When the user asks you to send a text message, use the sms function."
9      }
10    ],
11    "tools": [
12      {
13        "type": "sms",
14        "metadata": {
15          "from": "+15551234567" 
16        }
17      }
18    ]
19  }
20}

Dial Keypad (DTMF)

This function is provided when dtmf is included in the assistant’s list of available tools (see configuration options here). The assistant will be able to enter digits on the keypad. Useful for IVR navigation or data entry.

1{
2  "model": {
3    "provider": "openai",
4    "model": "gpt-4o",
5    "messages": [
6      {
7        "role": "system",
8        "content": "You are an assistant at a law firm. When you hit a menu, use the dtmf function to enter the digits."
9      }
10    ],
11    "tools": [
12      {
13          "type": "dtmf"
14      }
15    ]
16  }
17}

There are three methods for sending DTMF in a phone call:

  1. In-band: tones are transmitted as part of the regular audio stream. This is the simplest method, but it can suffer from quality issues if the audio stream is compressed or degraded.
  2. Out-of-band via RFC 2833: tones are transmitted separately from the audio stream, within RTP (Real-Time Protocol) packets. It’s typically more reliable than in-band DTMF, particularly for VoIP applications where the audio stream might be compressed. RFC 2833 is the standard that initially defined this method. It is now replaced by RFC 4733 but this method is still referred by RFC 2833.
  3. Out-of-band via SIP INFO messages: tones are sent as separate SIP INFO messages. While this can be more reliable than in-band DTMF, it’s not as widely supported as the RFC 2833 method.

Vapi’s DTMF tool integrates with telephony provider APIs to send DTMF tones using the out-of-band RFC 2833 method. This approach is widely supported and more reliable for transmitting the signals, especially in VoIP environments. Note, the tool’s effectiveness depends on the IVR system’s configuration and their capturing method. If you are running into issues, try different telephony providers or have your assistant say the options out loud if available.

API Request

This tool allows your assistant to make HTTP requests to any external API endpoint during conversations. This tool fills the gap between Vapi and your existing business logic, bringing your own endpoints into the conversation flow. See configuration options here.

Dynamic Variables with LiquidJS

Use LiquidJS syntax to reference conversation variables and user data in your URLs, headers, and request bodies. This allows your API requests to adapt dynamically based on the conversation context.

Basic Examples

GET Request Example

1{
2  "model": {
3    "provider": "openai",
4    "model": "gpt-4o",
5    "messages": [
6      {
7        "role": "system",
8        "content": "You help users check their order status. When they provide an order number, use the checkOrderStatus function."
9      }
10    ],
11    "tools": [
12      {
13        "type": "apiRequest",
14        "function": {
15          "name": "api_request_tool"
16        },
17        "name": "checkOrderStatus",
18        "url": "https://api.yourcompany.com/orders/{{orderNumber}}",
19        "method": "GET",
20        "body": {
21          "type": "object",
22          "properties": {
23            "orderNumber": {
24              "description": "The user's order number",
25              "type": "string"
26            }
27          },
28          "required": ["orderNumber"]
29        }
30      }
31    ]
32  }
33}

POST Request Example

1{
2  "model": {
3    "provider": "openai",
4    "model": "gpt-4o",
5    "messages": [
6      {
7        "role": "system",
8        "content": "You help users book appointments. When they want to schedule, use the bookAppointment function."
9      }
10    ],
11    "tools": [
12      {
13        "type": "apiRequest",
14        "function": {
15          "name": "api_request_tool"
16        },
17        "name": "bookAppointment",
18        "url": "https://api.yourcompany.com/appointments",
19        "method": "POST",
20        "headers": {
21          "type": "object",
22          "properties": {
23            "x-api-key": {
24              "type": "string",
25              "value": "123456789"
26            }
27          }
28        },
29        "body": {
30          "type": "object",
31          "properties": {
32            "date": {
33              "description": "The date of the appointment",
34              "type": "string"
35            },
36            "customerName": {
37              "description": "The name of the customer",
38              "type": "string"
39            },
40            "customerPhoneNumber": {
41              "description": "The phone number of the customer",
42              "type": "string"
43            }
44          },
45          "required": [
46            "date",
47            "customerName",
48            "customerPhoneNumber"
49          ]
50        }
51      }
52    ]
53  }
54}
Advanced Configuration

With Retry Logic

1{
2  "type": "apiRequest",
3  "function": {
4    "name": "api_request_tool"
5  },
6  "name": "checkOrderStatus",
7  "url": "https://api.yourcompany.com/orders/{{orderNumber}}",
8  "method": "GET",
9  "body": {
10    "type": "object",
11    "properties": {
12      "orderNumber": {
13        "description": "The user's order number",
14        "type": "string"
15      }
16    },
17    "required": [
18      "orderNumber"
19    ]
20  },
21  "backoffPlan": {
22    "type": "exponential",
23    "maxRetries": 3,
24    "baseDelaySeconds": 1
25  },
26  "timeoutSeconds": 45
27}

Custom Functions

The Custom Functions feature is being deprecated in favor of Tools. Please refer to the Tools section instead. We’re working on a solution to migrate your existing functions over to make this a seamless transtion.

In addition to the predefined functions, you can also define custom functions. These functions are similar to OpenAI functions and your chosen LLM will trigger them as needed based on your instructions.

The functions array in the assistant definition allows you to define custom functions that the assistant can call during a conversation. Each function is an object with the following properties:

  • name: The name of the function. It must be a string containing a-z, A-Z, 0-9, underscores, or dashes, with a maximum length of 64.
  • description: A brief description of what the function does. This is used by the AI to decide when and how to call the function.
  • parameters: An object that describes the parameters the function accepts. The type property should be “object”, and the properties property should be an object where each key is a parameter name and each value is an object describing the type and purpose of the parameter.

Here’s an example of a function definition:

1{
2  "functions": [
3    {
4      "name": "bookAppointment",
5      "description": "Used to book the appointment.",
6      "parameters": {
7        "type": "object",
8        "properties": {
9          "datetime": {
10            "type": "string",
11            "description": "The date and time of the appointment in ISO format."
12          }
13        }
14      }
15    }
16  ]
17}

In this example, the bookAppointment function accepts one parameter, datetime, which is a string representing the date and time of the appointment in ISO format.

In addition to defining custom functions, you can specify a serverUrl where Vapi will send the function call information. This URL can be configured at the account level or at the assistant level. At the account level, the serverUrl is set in the Vapi Dashboard. All assistants under the account will use this URL by default for function calls. At the assistant level, the serverUrl can be specified in the assistant configuration when creating or updating an assistant. This allows different assistants to use different URLs for function calls. If a serverUrl is specified at the assistant level, it will override the account-level Server URL.

If the serverUrl is not defined either at the account level or the assistant level, the function call will simply be added to the chat history. This can be particularly useful when you want a function call to trigger an action on the frontend.

For instance, the frontend can listen for specific function calls in the chat history and respond by updating the user interface or performing other actions. This allows for a dynamic and interactive user experience, where the frontend can react to changes in the conversation in real time.