From 24d670174538d317bd197bc9b84ff939f89a9708 Mon Sep 17 00:00:00 2001 From: stevenbdf Date: Mon, 16 Jun 2025 23:33:16 -0700 Subject: [PATCH 1/4] feat: add API Request tool docs --- fern/tools/default-tools.mdx | 143 ++++++++++++++++++++++++++++++++++- 1 file changed, 141 insertions(+), 2 deletions(-) diff --git a/fern/tools/default-tools.mdx b/fern/tools/default-tools.mdx index 428a91eea..49037ac68 100644 --- a/fern/tools/default-tools.mdx +++ b/fern/tools/default-tools.mdx @@ -1,10 +1,10 @@ --- title: Default Tools -subtitle: 'Adding Transfer Call, End Call, and Dial Keypad capabilities to your assistants.' +subtitle: 'Adding Transfer Call, End Call, Dial Keypad, and API Request capabilities to your assistants.' slug: tools/default-tools --- -Vapi voice assistants are given additional functions: `transferCall`,`endCall`, and `dtmf` (to dial a keypad with [DTMF](https://en.wikipedia.org/wiki/DTMF)). These functions can be used to transfer calls, hang up calls, and enter digits on the keypad. +Vapi voice assistants are given additional functions: `transferCall`, `endCall`, `dtmf` (to dial a keypad with [DTMF](https://en.wikipedia.org/wiki/DTMF)), and `apiRequest` (to make HTTP requests to your existing APIs). These functions can be used to transfer calls, hang up calls, enter digits on the keypad, and integrate with your existing business systems. 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. @@ -147,6 +147,145 @@ We called and navigated through the IVRs using three different strategies: The tool's effectiveness depends on the IVR system's configuration and DTMF capturing method. We are working to improve compatibility and reduce transmission delays for broader and more reliable support. +#### 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](/api-reference/tools/create). + +##### 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** +```json +{ + "model": { + "provider": "openai", + "model": "gpt-4o", + "messages": [ + { + "role": "system", + "content": "You help users check their order status. When they provide an order number, use the checkOrderStatus function." + } + ], + "tools": [ + { + "type": "apiRequest", + "function": { + "name": "api_request_tool" + }, + "name": "checkOrderStatus", + "url": "https://api.yourcompany.com/orders/{{orderNumber}}", + "method": "GET", + "body": { + "type": "object", + "properties": { + "orderNumber": { + "description": "The user's order number", + "type": "string" + } + }, + "required": ["orderNumber"] + } + } + ] + } +} +``` + +**POST Request Example** +```json +{ + "model": { + "provider": "openai", + "model": "gpt-4o", + "messages": [ + { + "role": "system", + "content": "You help users book appointments. When they want to schedule, use the bookAppointment function." + } + ], + "tools": [ + { + "type": "apiRequest", + "function": { + "name": "api_request_tool" + }, + "name": "bookAppointment", + "url": "https://api.yourcompany.com/appointments", + "method": "POST", + "headers": { + "type": "object", + "properties": { + "x-api-key": { + "type": "string", + "value": "123456789" + } + } + }, + "body": { + "type": "object", + "properties": { + "date": { + "description": "The date of the appointment", + "type": "string" + }, + "customerName": { + "description": "The name of the customer", + "type": "string" + }, + "customerPhoneNumber": { + "description": "The phone number of the customer", + "type": "string" + } + }, + "required": [ + "date", + "customerName", + "customerPhoneNumber" + ] + } + } + ] + } +} +``` + +##### Advanced Configuration + +**With Retry Logic** +```json +{ + "type": "apiRequest", + "function": { + "name": "api_request_tool" + }, + "name": "checkOrderStatus", + "url": "https://api.yourcompany.com/orders/{{orderNumber}}", + "method": "GET", + "body": { + "type": "object", + "properties": { + "orderNumber": { + "description": "The user's order number", + "type": "string" + } + }, + "required": [ + "orderNumber" + ] + }, + "backoffPlan": { + "initialDelayMs": 1000, + "maxDelayMs": 10000, + "backoffMultiplier": 2.0, + "maxRetries": 3 + }, + "timeoutSeconds": 45 +} +``` ### Custom Functions From 26b362ea10a7f488eca419a2acde3c4485e02f9a Mon Sep 17 00:00:00 2001 From: stevenbdf Date: Mon, 16 Jun 2025 23:39:02 -0700 Subject: [PATCH 2/4] feat: update DTMF docs --- fern/tools/default-tools.mdx | 26 +++----------------------- 1 file changed, 3 insertions(+), 23 deletions(-) diff --git a/fern/tools/default-tools.mdx b/fern/tools/default-tools.mdx index 49037ac68..3792586c0 100644 --- a/fern/tools/default-tools.mdx +++ b/fern/tools/default-tools.mdx @@ -94,6 +94,7 @@ This function is provided when `sms` is included in the assistant's list of avai #### Dial Keypad (DTMF) This function is provided when `dtmf` is included in the assistant's list of available tools (see configuration options [here](/api-reference/assistants/create#request.body.model.openai.tools.dtmf)). The assistant will be able to enter digits on the keypad. +Useful for IVR navigation or data entry. ```json { @@ -122,31 +123,10 @@ There are three methods for sending DTMF in a phone call: 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 uses in-band method. Please note that this method may not work with certain IVRs. If you are running into this issue, the recommended approach is to have your assistant say the options out loud if available. For example, when an IVR says "Press 1 or say Sales for the Sales department," prefer having the assistant say "Sales." +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. -##### Tool Effectiveness - -To evaluate this tool, we set up a Vapi assistant with the DTMF tool enabled and conducted calls to a range of IVR systems, including a Twilio IVR (configured via Studio Flows) and several third-party IVRs such as pharmacies and insurance companies. - -**Testing Methodology** - -We called and navigated through the IVRs using three different strategies: - -1. **Direct Dialpad**: calling from a personal phone and dialing options using the dialpad. -2. **Vapi DTMF Tool**: an assistant configured with the DTMF tool. -3. **Manual DTMF Sound**: calling from a personal phone and playing DTMF tones generated by software. _(similar approach as the Vapi DTMF Tool)_ - -**Key Findings** - -- The assistant successfully navigated some of the third-party IVRs. -- The assistant encountered issues with Twilio IVRs, likely due to Twilio's preference for RFC 2833. -- Observed occasional delays in DTMF tone transmission, which may affect effectiveness with IVRs that have short timeouts. - -**Conclusion** - -The tool's effectiveness depends on the IVR system's configuration and DTMF capturing method. We are working to improve compatibility and reduce transmission delays for broader and more reliable support. - #### 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. From ab60e8c598afa4c23a7543cab61f20a1be7c0507 Mon Sep 17 00:00:00 2001 From: stevenbdf Date: Mon, 16 Jun 2025 23:42:48 -0700 Subject: [PATCH 3/4] wording --- fern/tools/default-tools.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/tools/default-tools.mdx b/fern/tools/default-tools.mdx index 3792586c0..8871d4e7f 100644 --- a/fern/tools/default-tools.mdx +++ b/fern/tools/default-tools.mdx @@ -4,7 +4,7 @@ subtitle: 'Adding Transfer Call, End Call, Dial Keypad, and API Request capabili slug: tools/default-tools --- -Vapi voice assistants are given additional functions: `transferCall`, `endCall`, `dtmf` (to dial a keypad with [DTMF](https://en.wikipedia.org/wiki/DTMF)), and `apiRequest` (to make HTTP requests to your existing APIs). These functions can be used to transfer calls, hang up calls, enter digits on the keypad, and integrate with your existing business systems. +Vapi voice assistants are given additional functions: `transferCall`, `endCall`, `dtmf` (to dial a keypad with [DTMF](https://en.wikipedia.org/wiki/DTMF)), and `apiRequest`. These functions can be used to transfer calls, hang up calls, enter digits on the keypad, and integrate 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. From 2479b9d20f3dbfbd2d38b40754174f82253e3692 Mon Sep 17 00:00:00 2001 From: stevenbdf Date: Mon, 16 Jun 2025 23:46:41 -0700 Subject: [PATCH 4/4] advanced example --- fern/tools/default-tools.mdx | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/fern/tools/default-tools.mdx b/fern/tools/default-tools.mdx index 8871d4e7f..a259b5170 100644 --- a/fern/tools/default-tools.mdx +++ b/fern/tools/default-tools.mdx @@ -4,7 +4,7 @@ subtitle: 'Adding Transfer Call, End Call, Dial Keypad, and API Request capabili slug: tools/default-tools --- -Vapi voice assistants are given additional functions: `transferCall`, `endCall`, `dtmf` (to dial a keypad with [DTMF](https://en.wikipedia.org/wiki/DTMF)), and `apiRequest`. These functions can be used to transfer calls, hang up calls, enter digits on the keypad, and integrate with your existing APIs. +Vapi voice assistants are given additional functions: `transferCall`, `endCall`, `sms`, `dtmf` (to dial a keypad with [DTMF](https://en.wikipedia.org/wiki/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. @@ -258,10 +258,9 @@ Use **LiquidJS syntax** to reference conversation variables and user data in you ] }, "backoffPlan": { - "initialDelayMs": 1000, - "maxDelayMs": 10000, - "backoffMultiplier": 2.0, - "maxRetries": 3 + "type": "exponential", + "maxRetries": 3, + "baseDelaySeconds": 1 }, "timeoutSeconds": 45 }