From 589563e9400117cc96c77bed93f995e7532854b9 Mon Sep 17 00:00:00 2001 From: Arthur Chi Date: Thu, 27 Mar 2025 21:00:05 -0700 Subject: [PATCH 1/4] add outbound docs --- fern/apis/webhooks/openapi.yml | 2 +- fern/calls/call-outbound.mdx | 43 ++++++++++++++++++++++++++++++++++ fern/docs.yml | 10 +++++++- fern/phone-calling.mdx | 2 +- 4 files changed, 54 insertions(+), 3 deletions(-) create mode 100644 fern/calls/call-outbound.mdx diff --git a/fern/apis/webhooks/openapi.yml b/fern/apis/webhooks/openapi.yml index 5ef96413b..0ad26cdd9 100644 --- a/fern/apis/webhooks/openapi.yml +++ b/fern/apis/webhooks/openapi.yml @@ -28,7 +28,7 @@ paths: summary: Client Message description: | These are all the webhook messages that will be sent to the client-side SDKs during the call. - Configure the messages you'd like to receive in `assistant.clientMessages``. + Configure the messages you'd like to receive in `assistant.clientMessages`. requestBody: content: diff --git a/fern/calls/call-outbound.mdx b/fern/calls/call-outbound.mdx new file mode 100644 index 000000000..081027f2f --- /dev/null +++ b/fern/calls/call-outbound.mdx @@ -0,0 +1,43 @@ +## Introduction to Outbound Calling + +Vapi provides robust support for outbound calling, enabling programmatic initiation of calls to phone numbers. Through Vapi's outbound calling API, you can initiate both single and batch outbound calls to any phone number. For time-sensitive communications, you can schedule calls for future execution at specific dates and times. The platform provides comprehensive monitoring capabilities, allowing you to track call status in real-time and collect detailed analytics about your calling operations. Just like inbound calls, outbound calls support recording and automatic transcription, providing complete access to call content and conversation history. + +Whether you're implementing appointment reminders, automated surveys, or outbound call campaigns, Vapi's API enables straightforward integration of outbound calling functionality into your applications. + +## Prerequisites + +- **Vapi Account**: Access to the Vapi Dashboard for configuration. +- **Configured Assistant**: Either a saved assistant or a transient assistant. +- **Phone Number**: Either an imported phone number from one of the supported providers or a free Vapi number. (Note: You cannot make international calls with a free Vapi number). +- **Customer's Phone Number**: The phone number that you want to call. + +## Outbound Calls + +You can place an outbound call from one of your phone numbers using the [`/call`](/api-reference/calls/create-phone-call) endpoint. + +1. **Specify an Assistant:** you must specify either a transient assistant in the `assistant` field or reuse a saved assistant in the `assistantId` field. +2. **Get a Phone Number:** provide the `phoneNumberId` of the imported number or free Vapi number you wish to call from. +3. **Provide a Destination:** Finally, pass the customer's phone number or SIP URI in [`customer`](api-reference/calls/create#request.body.customer). + +Provide your authorization token and now we're ready to issue the API call! + +## Scheduling Outbound Calls + +To schedule a call for the future, use the [`schedulePlan`](api-reference/calls/create#request.body.schedulePlan) parameter and pass a future ISO date-time string to `earliestAt`. This will be the earliest time Vapi will attempt to trigger the outbound call. You may also provider `latestAt`, which will be the latest time Vapi will attempt to trigger the call. + +When you schedule a call, we will save the Assistant, Phone Number, and Customer Number resources and refetch them at the time of the call. If you choose to provide a saved assistant through `assistantId`, we will pick up the most up-to-date version of your assistant at the call time. Likewise, if you delete your saved assistant, the call will fail! To ensure the call is issued with a static version of an assistant, pass it as a transient assistant through the `assistant` parameter. + + +## Batch Calling + +To call more than one number at a time, use the [`customers`](api-reference/calls/create#request.body.customers) parameter to pass an array of `customer`. To provide customer specific assistant overrides, please call the endpoint separately for each destination number. + +Use both `customers` and `schedulePlan` together to schedule batched calls. + +Note: Vapi free numbers have limited number of outbound calls per day. Import a number from Twilio, Vonage, or Telnyx to scale without limits. + + + It is a violation of FCC law to dial phone numbers without consent in an + automated manner. See [Telemarketing Sales + Rule](/glossary#telemarketing-sales-rule) to learn more. + \ No newline at end of file diff --git a/fern/docs.yml b/fern/docs.yml index a36ce7b08..7793b4d60 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -201,7 +201,7 @@ navigation: contents: - page: Twilio path: advanced/sip/sip-twilio.mdx - - page: Telnyx + - page: Telnyx path: advanced/sip/sip-telnyx.mdx - page: Zadarma path: advanced/sip/sip-zadarma.mdx @@ -362,6 +362,8 @@ navigation: contents: - page: Call Forwarding path: call-forwarding.mdx + - page: Outbound Calls + path: calls/call-outbound.mdx - page: Dynamic Call Transfers path: calls/call-dynamic-transfers.mdx - page: Ended Reason @@ -402,6 +404,12 @@ navigation: - page: Server Authentication path: server-url/server-authentication.mdx + - section: Test + collapsed: true + contents: + - page: Test Suites + path: test/test-suites.mdx + - section: Community collapsed: true contents: diff --git a/fern/phone-calling.mdx b/fern/phone-calling.mdx index 7a4a0ba91..2e25d3eb7 100644 --- a/fern/phone-calling.mdx +++ b/fern/phone-calling.mdx @@ -17,7 +17,7 @@ If you want to use your own phone number, you can also use the dashboard or the You can place an outbound call from one of your phone numbers using the - [`/call/phone`](/api-reference/calls/create-phone-call) endpoint. If the system message will be + [`/call`](/api-reference/calls/create-phone-call) endpoint. If the system message will be different with every call, you can specify a temporary assistant in the `assistant` field. If you want to reuse an assistant, you can specify its ID in the `assistantId` field. From 06320b055c25c7322bd747b0f54a6bbb1d8120a0 Mon Sep 17 00:00:00 2001 From: Arthur Chi Date: Thu, 27 Mar 2025 22:54:43 -0700 Subject: [PATCH 2/4] fix --- fern/calls/call-outbound.mdx | 10 ++++------ fern/docs.yml | 17 ++++------------- 2 files changed, 8 insertions(+), 19 deletions(-) diff --git a/fern/calls/call-outbound.mdx b/fern/calls/call-outbound.mdx index 081027f2f..809fec18c 100644 --- a/fern/calls/call-outbound.mdx +++ b/fern/calls/call-outbound.mdx @@ -1,8 +1,6 @@ ## Introduction to Outbound Calling -Vapi provides robust support for outbound calling, enabling programmatic initiation of calls to phone numbers. Through Vapi's outbound calling API, you can initiate both single and batch outbound calls to any phone number. For time-sensitive communications, you can schedule calls for future execution at specific dates and times. The platform provides comprehensive monitoring capabilities, allowing you to track call status in real-time and collect detailed analytics about your calling operations. Just like inbound calls, outbound calls support recording and automatic transcription, providing complete access to call content and conversation history. - -Whether you're implementing appointment reminders, automated surveys, or outbound call campaigns, Vapi's API enables straightforward integration of outbound calling functionality into your applications. +Vapi’s outbound calling API lets you programmatically initiate single or batch calls to any phone number. You can schedule calls for specific dates and times, ideal for time-sensitive communications. Easily integrate outbound calling into your app for appointment reminders, automated surveys, and call campaigns. ## Prerequisites @@ -17,20 +15,20 @@ You can place an outbound call from one of your phone numbers using the [`/call` 1. **Specify an Assistant:** you must specify either a transient assistant in the `assistant` field or reuse a saved assistant in the `assistantId` field. 2. **Get a Phone Number:** provide the `phoneNumberId` of the imported number or free Vapi number you wish to call from. -3. **Provide a Destination:** Finally, pass the customer's phone number or SIP URI in [`customer`](api-reference/calls/create#request.body.customer). +3. **Provide a Destination:** Finally, pass the customer's phone number or SIP URI in [`customer`](api-reference/calls/create-phone-call#request.body.customer). Provide your authorization token and now we're ready to issue the API call! ## Scheduling Outbound Calls -To schedule a call for the future, use the [`schedulePlan`](api-reference/calls/create#request.body.schedulePlan) parameter and pass a future ISO date-time string to `earliestAt`. This will be the earliest time Vapi will attempt to trigger the outbound call. You may also provider `latestAt`, which will be the latest time Vapi will attempt to trigger the call. +To schedule a call for the future, use the [`schedulePlan`](api-reference/calls/create-phone-call#request.body.schedulePlan) parameter and pass a future ISO date-time string to `earliestAt`. This will be the earliest time Vapi will attempt to trigger the outbound call. You may also provider `latestAt`, which will be the latest time Vapi will attempt to trigger the call. When you schedule a call, we will save the Assistant, Phone Number, and Customer Number resources and refetch them at the time of the call. If you choose to provide a saved assistant through `assistantId`, we will pick up the most up-to-date version of your assistant at the call time. Likewise, if you delete your saved assistant, the call will fail! To ensure the call is issued with a static version of an assistant, pass it as a transient assistant through the `assistant` parameter. ## Batch Calling -To call more than one number at a time, use the [`customers`](api-reference/calls/create#request.body.customers) parameter to pass an array of `customer`. To provide customer specific assistant overrides, please call the endpoint separately for each destination number. +To call more than one number at a time, use the [`customers`](api-reference/calls/create-phone-call#request.body.customers) parameter to pass an array of `customer`. To provide customer specific assistant overrides, please call the endpoint separately for each destination number. Use both `customers` and `schedulePlan` together to schedule batched calls. diff --git a/fern/docs.yml b/fern/docs.yml index 7793b4d60..0960d7dc1 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -344,19 +344,6 @@ navigation: - page: Vapify path: providers/vapify.mdx - - section: Test - collapsed: true - contents: - - page: Test Suites - path: test/test-suites.mdx - - page: Chat Testing - path: test/chat-testing.mdx - - page: Voice Testing - path: test/voice-testing.mdx - - - section: Deploy - collapsed: true - contents: - section: Calls path: phone-calling.mdx contents: @@ -409,6 +396,10 @@ navigation: contents: - page: Test Suites path: test/test-suites.mdx + - page: Chat Testing + path: test/chat-testing.mdx + - page: Voice Testing + path: test/voice-testing.mdx - section: Community collapsed: true From a0cb8a2c64001d98ccdac3d8af76d0668794c0da Mon Sep 17 00:00:00 2001 From: Arthur Chi Date: Thu, 27 Mar 2025 23:24:40 -0700 Subject: [PATCH 3/4] fix --- fern/calls/call-outbound.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/fern/calls/call-outbound.mdx b/fern/calls/call-outbound.mdx index 809fec18c..0ae1baa00 100644 --- a/fern/calls/call-outbound.mdx +++ b/fern/calls/call-outbound.mdx @@ -15,20 +15,20 @@ You can place an outbound call from one of your phone numbers using the [`/call` 1. **Specify an Assistant:** you must specify either a transient assistant in the `assistant` field or reuse a saved assistant in the `assistantId` field. 2. **Get a Phone Number:** provide the `phoneNumberId` of the imported number or free Vapi number you wish to call from. -3. **Provide a Destination:** Finally, pass the customer's phone number or SIP URI in [`customer`](api-reference/calls/create-phone-call#request.body.customer). +3. **Provide a Destination:** Finally, pass the customer's phone number or SIP URI in [`customer`](/api-reference/calls/create-phone-call#request.body.customer). Provide your authorization token and now we're ready to issue the API call! ## Scheduling Outbound Calls -To schedule a call for the future, use the [`schedulePlan`](api-reference/calls/create-phone-call#request.body.schedulePlan) parameter and pass a future ISO date-time string to `earliestAt`. This will be the earliest time Vapi will attempt to trigger the outbound call. You may also provider `latestAt`, which will be the latest time Vapi will attempt to trigger the call. +To schedule a call for the future, use the [`schedulePlan`](/api-reference/calls/create-phone-call#request.body.schedulePlan) parameter and pass a future ISO date-time string to `earliestAt`. This will be the earliest time Vapi will attempt to trigger the outbound call. You may also provider `latestAt`, which will be the latest time Vapi will attempt to trigger the call. When you schedule a call, we will save the Assistant, Phone Number, and Customer Number resources and refetch them at the time of the call. If you choose to provide a saved assistant through `assistantId`, we will pick up the most up-to-date version of your assistant at the call time. Likewise, if you delete your saved assistant, the call will fail! To ensure the call is issued with a static version of an assistant, pass it as a transient assistant through the `assistant` parameter. ## Batch Calling -To call more than one number at a time, use the [`customers`](api-reference/calls/create-phone-call#request.body.customers) parameter to pass an array of `customer`. To provide customer specific assistant overrides, please call the endpoint separately for each destination number. +To call more than one number at a time, use the [`customers`](/api-reference/calls/create-phone-call#request.body.customers) parameter to pass an array of `customer`. To provide customer specific assistant overrides, please call the endpoint separately for each destination number. Use both `customers` and `schedulePlan` together to schedule batched calls. From 0f11197d030f152f7610a591a4cad506e6ce7542 Mon Sep 17 00:00:00 2001 From: Arthur Chi Date: Thu, 27 Mar 2025 23:33:32 -0700 Subject: [PATCH 4/4] example --- fern/calls/call-outbound.mdx | 40 ++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/fern/calls/call-outbound.mdx b/fern/calls/call-outbound.mdx index 0ae1baa00..3f3a119c0 100644 --- a/fern/calls/call-outbound.mdx +++ b/fern/calls/call-outbound.mdx @@ -19,12 +19,34 @@ You can place an outbound call from one of your phone numbers using the [`/call` Provide your authorization token and now we're ready to issue the API call! +```jsx +{ + "assistantId": "assistant-id", + "phoneNumberId": "phone-number-id", + "customer": { + "number": "+11231231234" + } +} +``` + ## Scheduling Outbound Calls To schedule a call for the future, use the [`schedulePlan`](/api-reference/calls/create-phone-call#request.body.schedulePlan) parameter and pass a future ISO date-time string to `earliestAt`. This will be the earliest time Vapi will attempt to trigger the outbound call. You may also provider `latestAt`, which will be the latest time Vapi will attempt to trigger the call. When you schedule a call, we will save the Assistant, Phone Number, and Customer Number resources and refetch them at the time of the call. If you choose to provide a saved assistant through `assistantId`, we will pick up the most up-to-date version of your assistant at the call time. Likewise, if you delete your saved assistant, the call will fail! To ensure the call is issued with a static version of an assistant, pass it as a transient assistant through the `assistant` parameter. +```jsx +{ + "assistantId": "assistant-id", + "phoneNumberId": "phone-number-id", + "customer": { + "number": "+11231231234" + }, + "schedulePlan": { + "earliestAt": "2025-05-30T00:00:00Z" + } +} +``` ## Batch Calling @@ -32,6 +54,24 @@ To call more than one number at a time, use the [`customers`](/api-reference/cal Use both `customers` and `schedulePlan` together to schedule batched calls. +```jsx +{ + "assistantId": "assistant-id", + "phoneNumberId": "phone-number-id", + "customers": [ + { + "number": "+11231231234" + }, + { + "number": "+12342342345" + } + ], + "schedulePlan": { + "earliestAt": "2025-05-30T00:00:00Z" + } +} +``` + Note: Vapi free numbers have limited number of outbound calls per day. Import a number from Twilio, Vonage, or Telnyx to scale without limits.