|
| 1 | +## Introduction to Outbound Calling |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | +## Prerequisites |
| 6 | + |
| 7 | +- **Vapi Account**: Access to the Vapi Dashboard for configuration. |
| 8 | +- **Configured Assistant**: Either a saved assistant or a transient assistant. |
| 9 | +- **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). |
| 10 | +- **Customer's Phone Number**: The phone number that you want to call. |
| 11 | + |
| 12 | +## Outbound Calls |
| 13 | + |
| 14 | +You can place an outbound call from one of your phone numbers using the [`/call`](/api-reference/calls/create-phone-call) endpoint. |
| 15 | + |
| 16 | +1. **Specify an Assistant:** you must specify either a transient assistant in the `assistant` field or reuse a saved assistant in the `assistantId` field. |
| 17 | +2. **Get a Phone Number:** provide the `phoneNumberId` of the imported number or free Vapi number you wish to call from. |
| 18 | +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). |
| 19 | + |
| 20 | +Provide your authorization token and now we're ready to issue the API call! |
| 21 | + |
| 22 | +```jsx |
| 23 | +{ |
| 24 | + "assistantId": "assistant-id", |
| 25 | + "phoneNumberId": "phone-number-id", |
| 26 | + "customer": { |
| 27 | + "number": "+11231231234" |
| 28 | + } |
| 29 | +} |
| 30 | +``` |
| 31 | + |
| 32 | +## Scheduling Outbound Calls |
| 33 | + |
| 34 | +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. |
| 35 | + |
| 36 | +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. |
| 37 | + |
| 38 | +```jsx |
| 39 | +{ |
| 40 | + "assistantId": "assistant-id", |
| 41 | + "phoneNumberId": "phone-number-id", |
| 42 | + "customer": { |
| 43 | + "number": "+11231231234" |
| 44 | + }, |
| 45 | + "schedulePlan": { |
| 46 | + "earliestAt": "2025-05-30T00:00:00Z" |
| 47 | + } |
| 48 | +} |
| 49 | +``` |
| 50 | + |
| 51 | +## Batch Calling |
| 52 | + |
| 53 | +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. |
| 54 | + |
| 55 | +Use both `customers` and `schedulePlan` together to schedule batched calls. |
| 56 | + |
| 57 | +```jsx |
| 58 | +{ |
| 59 | + "assistantId": "assistant-id", |
| 60 | + "phoneNumberId": "phone-number-id", |
| 61 | + "customers": [ |
| 62 | + { |
| 63 | + "number": "+11231231234" |
| 64 | + }, |
| 65 | + { |
| 66 | + "number": "+12342342345" |
| 67 | + } |
| 68 | + ], |
| 69 | + "schedulePlan": { |
| 70 | + "earliestAt": "2025-05-30T00:00:00Z" |
| 71 | + } |
| 72 | +} |
| 73 | +``` |
| 74 | + |
| 75 | +Note: Vapi free numbers have limited number of outbound calls per day. Import a number from Twilio, Vonage, or Telnyx to scale without limits. |
| 76 | + |
| 77 | +<Warning> |
| 78 | + It is a violation of FCC law to dial phone numbers without consent in an |
| 79 | + automated manner. See [Telemarketing Sales |
| 80 | + Rule](/glossary#telemarketing-sales-rule) to learn more. |
| 81 | +</Warning> |
0 commit comments