Custom Tools

This guide shows you how to create custom tools for your Vapi assistants. We recommend using the Vapi dashboard’s dedicated Tools section, which provides a visual interface for creating and managing tools that can be reused across multiple assistants. For advanced users, API configuration is also available.

Creating Tools in the Dashboard (Recommended)

Step 1: Navigate to the Tools Section

1. Open your Vapi Dashboard
2. Click Tools in the left sidebar
3. Click Create Tool to start building your custom tool

Step 2: Configure Your Tool

The dashboard provides a user-friendly interface to configure your tool:

1. Tool Type: Select “Function” for custom API integrations
2. Tool Name: Give your tool a descriptive name (e.g., “Weather Lookup”)
3. Description: Explain what your tool does
4. Tool Configuration:
   • Tool Name: The identifier for your function (e.g., get_weather)
   • Parameters: Define the input parameters your function expects
   • Server URL: The endpoint where your function is hosted

Step 3: Configure Messages

Set up the messages your assistant will speak during tool execution. For example, if you want custom messages you can add something like this:

• Request Start: “Checking the weather forecast. Please wait…”
• Request Complete: “The weather information has been retrieved.”
• Request Failed: “I couldn’t get the weather information right now.”
• Request Delayed: “There’s a slight delay with the weather service.”

Step 4: Advanced Settings

Configure additional options:

• Async Mode: Enable if the tool should run asynchronously
• Timeout Settings: Set how long to wait for responses
• Error Handling: Define fallback behaviors

Example: Creating a Weather Tool

Let’s walk through creating a weather lookup tool:

Dashboard Configuration

1. Tool Name: “Weather Lookup”
2. Description: “Retrieves current weather information for any location”
3. Function Name: get_weather
4. Parameters:
   • location (string, required): “The city or location to get weather for”
5. Server URL: https://api.openweathermap.org/data/2.5/weather

Messages Configuration

• Request Start: “Let me check the current weather for you…”
• Request Complete: “Here’s the weather information you requested.”
• Request Failed: “I’m having trouble accessing weather data right now.”

Using Tools in Assistants

Once created, your tools can be easily added to any assistant:

In the Dashboard

1. Go to Assistants → Select your assistant
2. Navigate to the Tools tab
3. Click Add Tool and select your custom tool from the dropdown
4. Save your assistant configuration

In Workflows

Tools created in the Tools section are automatically available in the workflow builder:

1. Add a Tool Node to your workflow
2. Select your custom tool from the Tool dropdown
3. Configure any node-specific settings

Alternative: API Configuration

For advanced users who prefer programmatic control, you can also create and manage tools via the Vapi API:

Creating Tools via API

$
curl --location 'https://api.vapi.ai/tool' \
>
--header 'Content-Type: application/json' \
>
--header 'Authorization: Bearer <YOUR_API_KEY>' \
>
--data '{
>
    "type": "function",
>
    "function": {
>
        "name": "get_weather",
>
        "description": "Retrieves current weather information for any location",
>
        "parameters": {
>
            "type": "object",
>
            "properties": {
>
                "location": {
>
                    "type": "string",
>
                    "description": "The city or location to get weather for"
>
                }
>
            },
>
            "required": ["location"]
>
        }
>
    },
>
    "server": {
>
        "url": "https://api.openweathermap.org/data/2.5/weather"
>
    }
>
}'

Adding Tools to Assistants via API

$
curl --location --request PATCH 'https://api.vapi.ai/assistant/ASSISTANT_ID' \
>
--header 'Authorization: Bearer <YOUR_API_KEY>' \
>
--header 'Content-Type: application/json' \
>
--data '{
>
    "model": {
>
        "provider": "openai",
>
        "model": "gpt-4",
>
        "toolIds": ["your-tool-id-here"]
>
    }
>
}'

Request Format: Understanding the Tool Call Request

When your server receives a tool call request from Vapi, it will be in the following format:

1
{
2
    "message": {
3
        "timestamp": 1678901234567,
4
        "type": "tool-calls",
5
        "toolCallList": [
6
            {
7
                "id": "toolu_01DTPAzUm5Gk3zxrpJ969oMF",
8
                "name": "get_weather",
9
                "arguments": {
10
                    "location": "San Francisco"
11
                }
12
            }
13
        ],
14
        "toolWithToolCallList": [
15
            {
16
                "type": "function",
17
                "name": "get_weather",
18
                "parameters": {
19
                    "type": "object",
20
                    "properties": {
21
                        "location": {
22
                            "type": "string"
23
                        }
24
                    }
25
                },
26
                "description": "Retrieves the current weather for a specified location"
27
            },
28
            "server": {
29
                "url": "https://api.openweathermap.org/data/2.5/weather"
30
            },
31
            "messages": [],
32
            "toolCall": {
33
                "id": "toolu_01DTPAzUm5Gk3zxrpJ969oMF",
34
                "type": "function",
35
                "function": {
36
                    "name": "get_weather",
37
                    "parameters": {
38
                        "location": "San Francisco"
39
                    }
40
                }
41
            }
42
        ],
43
        "artifact": {
44
            "messages": []
45
        },
46
        "assistant": {
47
            "name": "Weather Assistant",
48
            "description": "An assistant that provides weather information",
49
            "model":{},
50
            "voice":{},
51
            "artifactPlans":{},
52
            "startSpeakingPlan":{}
53
        },
54
        "call": {
55
            "id": "call-uuid",
56
            "orgId": "org-uuid",
57
            "type": "webCall",
58
            "assistant": {}
59
        }
60
    }
61
}

Server Response Format: Providing Results and Context

When your Vapi assistant calls a tool (via the server URL you configured), your server will receive an HTTP request containing information about the tool call. Upon processing the request and executing the desired function, your server needs to send back a response in the following JSON format:

1
{
2
    "results": [
3
        {
4
            "toolCallId": "X",
5
            "result": "Y"
6
        }
7
    ]
8
}

Breaking down the components:

• toolCallId (X): This is a unique identifier included in the initial request from Vapi. It allows the assistant to match the response with the corresponding tool call, ensuring accurate processing and context preservation.
• result (Y): This field holds the actual output or result of your tool’s execution. The format and content of “result” will vary depending on the specific function of your tool. It could be a string, a number, an object, an array, or any other data structure that is relevant to the tool’s purpose.

Example:

Let’s revisit the weather tool example from before. If the tool successfully retrieves the weather for a given location, the server response might look like this:

1
{
2
  "results": [
3
    {
4
      "toolCallId": "call_VaJOd8ZeZgWCEHDYomyCPfwN",
5
      "result": "San Francisco's weather today is 62°C, partly cloudy."
6
    }
7
  ]
8
}

Some Key Points:

• Pay attention to the required parameters and response format of your functions.
• Ensure your server is accessible and can handle the incoming requests from Vapi.
• Make sure to add “Tools Calls” in both the Server and Client messages and remove the function calling from it.

By following these guidelines and adapting the sample payload, you can easily configure a variety of tools to expand your Vapi assistant’s capabilities and provide a richer, more interactive user experience.

Video Tutorial: