outbound calling quickstart (#60)

* Scenario * have to duplicate — conversion to jsx for vars would break formatting * assistant setup * Get a Phone Number * update * video
VapiAI · Apr 18, 2024 · 56c3155 · 56c3155
1 parent 3955e39
commit 56c3155
Show file tree

Hide file tree

Showing 8 changed files with 307 additions and 7 deletions.
diff --git a/glossary.mdx b/glossary.mdx
@@ -80,6 +80,14 @@ An abbreviation used for "Speech-to-text". The process of converting physical so
 
 ## T
 
+### Telemarketing Sales Rule
+
+The Telemarketing Sales Rule (or "TSR" for short) is a regulation established by the Federal Trade Commission ([ftc.gov](https://www.ftc.gov/)) in the United States to protect consumers from deceptive and abusive telemarketing practices.
+
+**You may only conduct outbound calls to phone numbers which you have consent to contact.** Violating TSR rules can result in significant civil (or even criminal) penalties.
+
+Learn more on the [FCC website](https://www.ftc.gov/legal-library/browse/rules/telemarketing-sales-rule).
+
 ### TTS
 
 An abbreviation used for "Text-to-speech". The process of converting raw text into playable audio data.

diff --git a/introduction.mdx b/introduction.mdx
@@ -63,8 +63,14 @@ Get up & running in minutes with one of our [quickstart](/quickstart) guides:
   >
     Quickly get started handling inbound phone calls.
   </Card>
-  <Card title="Web Quickstart" icon="browser" iconType="regular" color="#54a7ff">
-    Coming Soon.
+  <Card
+    title="Outbound Calling"
+    icon="phone-arrow-up-right"
+    iconType="solid"
+    color="#54a7ff"
+    href="/quickstart/phone/outbound"
+  >
+    Quickly get started sending outbound phone calls.
   </Card>
 </CardGroup>
 

diff --git a/mint.json b/mint.json
@@ -98,7 +98,7 @@
             "quickstart/dashboard",
             {
               "group": "Phone Calling",
-              "pages": ["quickstart/phone/inbound"]
+              "pages": ["quickstart/phone/inbound", "quickstart/phone/outbound"]
             }
           ]
         }

diff --git a/quickstart.mdx b/quickstart.mdx
@@ -81,8 +81,13 @@ We will walk through the same quickstart demo with every major way you can integ
   >
     Quickly get started handling inbound phone calls.
   </Card>
-  <Card title="Outbound Calling Quickstart" icon="phone-arrow-up-right" iconType="solid">
-    Coming Soon.
+  <Card
+    title="Outbound Calling Quickstart"
+    icon="phone-arrow-up-right"
+    iconType="solid"
+    href="/quickstart/phone/outbound"
+  >
+    Quickly get started sending outbound phone calls.
   </Card>
 </CardGroup>
 

diff --git a/quickstart/phone/outbound.mdx b/quickstart/phone/outbound.mdx
@@ -4,4 +4,285 @@ sidebarTitle: "Outbound"
 description: "Quickstart sending outbound calls with Vapi."
 ---
 
-lorem
+import GetAPhoneNumberSnippet from "/snippets/quickstart/phone/get-a-phone-number.mdx";
+import { YouTubeEmbed } from "/snippets/video/videos.mdx";
+
+<YouTubeEmbed
+  videoUrl="https://www.youtube.com/embed/e_tdhA7S9DI?si=Sl3GXq17KqT9Wzzp"
+  altTitle="Quickstart: Outbound Calling"
+/>
+
+An outbound call is a phone call that is dialed and goes **"out"** from a phone number, & in our case, our AI assistant will be doing the dialing.
+
+There are **3 steps** we will cover to send our first outbound phone call:
+
+1. **Create an Assistant:** we will create an [assistant](/assistants) & instruct it on how to conduct itself during the call
+2. **Get a Phone Number:** we can either import existing numbers we own, or purchase one through Vapi
+3. **Call Your Number:** we will set our assistant as the dialer, set the destination phone number, then make the call
+
+we can then send the outbound call (hopefully someone picks up!)
+
+<Warning>
+  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.
+</Warning>
+
+## Vapi’s Pizzeria
+
+We will be implementing a simple order-taking assistant for a pizza shop called “Vapi’s Pizzeria”.
+
+Vapi’s has 3 types of menu items: `pizza`, `side`s, & `drink`s. Customers will be ordering 1 of each.
+
+**Outbound Scenario:** We will imagine we are calling back a customer who originally called in to place an order. Our assistant is calling back to complete the ordering process with the customer.
+
+<Frame caption="Customers can order 3 items: 1 pizza, 1 side, & 1 drink. The assistant will call the customer (who got disconnected) & finish the ordering process.">
+  <img src="/static/images/quickstart/vapis-pizzeria.png" />
+</Frame>
+
+## Assistant Setup
+
+First we're going to set up our assistant in the dashboard. Once our assistant’s **transcriber**, **model**, & **voice** are set up, we can have it call the customer to finish the order.
+
+<Info>You can visit your dashboard by going to [dashboard.vapi.ai](https://dashboard.vapi.ai)</Info>
+
+<AccordionGroup>
+  <Accordion title="Sign-up or Log-in to Vapi" icon="user-plus" iconType="solid">
+    If you haven't already signed-up, you're going to need an account before you can use the web dashboard. When you visit [dashboard.vapi.ai](https://dashboard.vapi.ai) you may see something like this:
+
+    <Frame>
+      <img src="/static/images/quickstart/dashboard/auth-ui.png" />
+    </Frame>
+
+    Sign-up for an account (or log-in to your existing account) — you will then find yourself inside the web dashboard. It will look something like this:
+
+    <Frame caption="Your dashboard may look a bit different if you already have an account with assistants in it. The main idea is that we’re in the dashboard now.">
+      <img src="/static/images/quickstart/dashboard/vapi-dashboard-post-signup.png" />
+    </Frame>
+
+  </Accordion>
+  <Accordion title="Create an Assistant" icon="layer-plus" iconType="solid">
+    Now that you're in your dashboard, we're going to create an [assistant](/assistants).
+
+    Assistants are at the heart of how Vapi models AI voice agents — we will be setting certain properties on a new assistant to model an order-taking agent.
+
+    Once in the "Assistants" dashboard tab (you should be in it by-default after log-in), you will see a button to create a new assistant.
+
+    <Frame caption="Ensure you are in the 'Assistants' dashboard tab, then this button will allow you to begin the assistant creation flow.">
+      <img src="/static/images/quickstart/dashboard/create-new-assistant-button.png" />
+    </Frame>
+
+    After clicking the create new assistant button, you will see a pop-up modal that asks you to pick a starter template. For our example we will start from a blank slate so choose the `Blank Template` option.
+
+    <Frame caption="Ensure you are in the 'Assistants' dashboard tab, then this button will allow you to begin the assistant creation flow.">
+      <img src="/static/images/quickstart/dashboard/choose-blank-template.png" />
+    </Frame>
+
+    You will then be able to name your assistant — you can name it whatever you'd like (`Vapi’s Pizza Front Desk`, for example):
+
+    <Info>
+      This name is only for internal labeling use. It is not an identifier, nor will the assistant be
+      aware of this name.
+    </Info>
+
+    <Frame caption="Name your assistant.">
+      <img src="/static/images/quickstart/dashboard/name-your-assistant.png" />
+    </Frame>
+
+    Once you have named your assistant, you can hit "Create" to create it. You will then see something like this:
+
+    <Frame caption="The assistant overview. You can edit your assistant’s transcriber, model, & voice — and edit other advanced configuration.">
+      <img src="/static/images/quickstart/dashboard/assistant-created.png" />
+    </Frame>
+
+    This is the assistant overview view — it gives you the ability to edit different attributes about your assistant, as well as see **cost** & **latency** projection information for each portion of it’s voice pipeline (this is very important data to have handy when building out your assistants).
+
+  </Accordion>
+  <Accordion title="Model Setup" icon="microchip" iconType="solid">
+    Now we’re going to set the "brains" of the assistant, the large language model. We're going to be using `GPT-4` (from [OpenAI](https://openai.com/)) for this demo (though you're free to use `GPT-3.5`, or any one of your favorite LLMs).
+
+    <AccordionGroup>
+      <Accordion title="Set Your OpenAI Provider Key (optional)" icon="key" iconType="solid">
+        Before we proceed, we can set our [provider key](/provider-keys) for OpenAI (this is just your OpenAI secret key).
+
+        <Note>
+          You can see all of your provider keys in the "Provider Keys" dashboard tab. You can also go
+          directly to [dashboard.vapi.ai/keys](https://dashboard.vapi.ai/keys).
+        </Note>
+
+        Vapi uses [provider keys](/provider-keys) you provide to communicate with LLM, TTS, & STT vendors on your behalf. It is most ideal that we set keys for the vendors we intend to use ahead of time.
+
+        <Frame caption="We set our provider key for OpenAI so Vapi can make requests to their API.">
+          <img src="/static/images/quickstart/dashboard/model-provider-keys.png" />
+        </Frame>
+
+        While we're here it'd be ideal for you to go & set up provider keys for other providers you're familiar with & intend to use later.
+      </Accordion>
+      <Accordion title="Set a First Message" icon="message" iconType="light">
+        Assistants can **optionally** be configured with a `First Message`. This first message will be spoken by your assistant when either:
+
+        - **A Web Call Connects:** when a web call is started with your assistant
+        - **An Inbound Call is Picked-up:** an [inbound call](/glossary#inbound-call) is picked-up & answered by your assistant
+        - **An Outbound Call is Dialed & Picked-up:** an [outbound call](/glossary#outbound-call) is dialed by your assistant & a person picks up
+
+        <Warning>
+          Note that this first message cannot be interrupted & is guaranteed to be spoken. Certain use cases
+          need a first message, while others do not.
+        </Warning>
+
+        For our use case, we will want a first message. Since we are calling the customer back it would be ideal for us to have a first message like this:
+
+        ```text
+        Hi this is Jennifer from Vappy’s Pizzeria giving you a call back since we got disconnected. Would you like to finish your order with us?
+        ```
+
+        <Info>
+          Some text-to-speech voices may struggle to pronounce 'Vapi' correctly, compartmentalizing it to be
+          spoken letter by letter "V. A. P. I."
+
+        Some aspects of configuring your voice pipeline will require tweaks like this to get the target
+        behaviour you want.
+
+        </Info>
+
+        This will be spoken by the assistant when a web or inbound phone call is received.
+      </Accordion>
+      <Accordion title="Set the System Prompt" icon="message" iconType="solid">
+        We will now set the `System Prompt` for our assistant. If you're familiar with OpenAI's API, this is the first prompt in the message list that we feed our LLM (learn more about prompt engineering on the [OpenAI docs](https://platform.openai.com/docs/guides/prompt-engineering)).
+
+        The system prompt can be used to configure the context, role, personality, instructions and so on for the assistant.
+
+        Since we are calling the customer back, we will tweak the base prompt a bit so the model understands the situation & new goal (recovering the order).
+
+        A system prompt like this will give us the behaviour we want:
+
+        ```text
+        You are a voice assistant for Vappy’s Pizzeria,
+        a pizza shop located on the Internet.
+
+        Your job is to take the order of customers calling in. The menu has only 3 types
+        of items: pizza, sides, and drinks. There are no other types of items on the menu.
+
+        1) There are 3 kinds of pizza: cheese pizza, pepperoni pizza, and vegetarian pizza
+        (often called "veggie" pizza).
+        2) There are 3 kinds of sides: french fries, garlic bread, and chicken wings.
+        3) There are 2 kinds of drinks: soda, and water. (if a customer asks for a
+        brand name like "coca cola", just let them know that we only offer "soda")
+
+        Customers can only order 1 of each item. If a customer tries to order more
+        than 1 item within each category, politely inform them that only 1 item per
+        category may be ordered.
+
+        Customers must order 1 item from at least 1 category to have a complete order.
+        They can order just a pizza, or just a side, or just a drink.
+
+        Be sure to introduce the menu items, don't assume that the caller knows what
+        is on the menu (most appropriate at the start of the conversation).
+
+        If the customer goes off-topic or off-track and talks about anything but the
+        process of ordering, politely steer the conversation back to collecting their order.
+
+        Once you have all the information you need pertaining to their order, you can
+        end the conversation. You can say something like "Awesome, we'll have that ready
+        for you in 10-20 minutes." to naturally let the customer know the order has been
+        fully communicated.
+
+        It is important that you collect the order in an efficient manner (succinct replies
+        & direct questions). You only have 1 task here, and it is to collect the customers
+        order, then end the conversation.
+
+        - Be sure to be kind of funny and witty!
+        - Keep all your responses short and simple. Use casual language, phrases like "Umm...", "Well...", and "I mean" are preferred.
+        - This is a voice conversation, so keep your responses short, like in a real conversation. Don't ramble for too long.
+
+        You are calling back a customer after the call got disconnected while they were
+        ordering. Your job is to help them complete their order.
+        ```
+
+        You can copy & paste the above prompt into the `System Prompt` field. Now the model configuration for your assistant should look something like this:
+
+        <Frame caption="Note how our model provider is set to OpenAI & the model is set to GPT-4.">
+          <img src="/static/images/quickstart/phone/outbound/assistant-model-setup.png" />
+        </Frame>
+      </Accordion>
+    </AccordionGroup>
+
+  </Accordion>
+  <Accordion title="Transcriber Setup" icon="microphone" iconType="solid">
+    The transcriber is what turns user speech into processable text for our LLM. This is the first step in the end-to-end voice pipeline.
+
+    <AccordionGroup>
+      <Accordion title="Set Your Deepgram Provider Key (optional)" icon="key" iconType="solid">
+        We will be using [Deepgram](https://deepgram.com) (which provides blazing-fast & accurate Speech-to-Text) as our STT provider.
+
+        We will set our provider key for them in "Provider Keys":
+
+        <Frame>
+          <img src="/static/images/quickstart/dashboard/transcriber-providers-keys.png" />
+        </Frame>
+      </Accordion>
+      <Accordion title="Set Transcriber" icon="language" iconType="solid">
+        We will set the model to `Nova 2` & the language to `en` for English. Now your assistant's transcriber configuration should look something like this:
+
+        <Frame caption="Note how our transcriber is set to 'deepgram', the model is set to 'Nova 2', & the language is set to English.">
+          <img src="/static/images/quickstart/dashboard/assistant-transcriber-config.png" />
+        </Frame>
+      </Accordion>
+    </AccordionGroup>
+
+  </Accordion>
+  <Accordion title="Voice Setup" icon="head-side-cough" iconType="solid">
+    The final portion of the voice pipeline is turning LLM output-text into speech. This process is called "Text-to-speech" (or TTS for short).
+
+    We will be using a voice provider called [PlayHT](https://play.ht) (they have very conversational voices), & a voice provided by them labeled `Jennifer` (`female`, `en-US`).
+
+    You are free to use your favorite TTS voice platform here. [ElevenLabs](https://elevenlabs.io/) is
+    another alternative — by now you should get the flow of plugging in vendors into Vapi (add
+    provider key + pick provider in assistant config).
+
+    You can skip the next step(s) if you don't intend to use PlayHT.
+
+    <AccordionGroup>
+      <Accordion title="Set Your PlayHT Provider Key (optional)" icon="key" iconType="solid">
+        If you haven't already, sign up for an account with PlayHT at [play.ht](https://play.ht). Since their flows are liable to change — you can just grab your `API Key` & `User ID` from them.
+
+        <Frame>
+          <img src="/static/images/quickstart/dashboard/voice-provider-keys.png" />
+        </Frame>
+      </Accordion>
+      <Accordion title="Set Voice" icon="person" iconType="solid">
+        You will want to select `playht` in the "provider" field, & `Jennifer` in the "voice" field. We will leave all of the other settings untouched.
+
+        <Frame caption="Each voice provider offers a host of settings you can modulate to customize voices. Here we will leave all the defaults alone.">
+          <img src="/static/images/quickstart/dashboard/assistant-voice-config.png" />
+        </Frame>
+      </Accordion>
+    </AccordionGroup>
+
+  </Accordion>
+</AccordionGroup>
+
+## Get a Phone Number
+
+Now that we've configured how our assistant will behave, we want to figure out how to dial calls with it. We will need a phone number that we can call from.
+
+<GetAPhoneNumberSnippet />
+
+## Call Your Number
+
+We can now make outbound calls to phone numbers, setting our assistant as the one doing the dialing.
+
+In the phone numbers section of the dashboard, go to your phone number detail page. We will:
+
+1. fill out **our own phone number** as the number to dial
+2. set our assistant as the one doing the calling
+
+<Frame caption="When we hit the call button, our assistant will make the outbound call to the phone number.">
+  <img src="/static/images/quickstart/phone/outbound/dial-outbound-call-dashboard.png" />
+</Frame>
+
+You can now hit the call button to make the outbound call. Your assistant will dial the phone number & manage the order recovery process.
+
+<Tip>
+  Your assistant won't yet be able to hang-up the phone at the end of the call. We will learn more
+  about configuring call end behaviour in later guides.
+</Tip>
diff --git a/snippets/quickstart/phone/get-a-phone-number.mdx b/snippets/quickstart/phone/get-a-phone-number.mdx
@@ -16,7 +16,7 @@ There are **2 ways** we can get a phone number into our Vapi account:
   <Accordion title="Import from Twilio or Vonage" icon="hashtag" iconType="regular">
     We can also import an existing phone number we already own with either Twilio or Vonage.
 
-    For example's sake, we will proceed with **Twilio** (though the steps are the same for Vonage as
+    For example's sake, we will proceed with [**Twilio**](https://twilio.com) (though the steps are the same for Vonage as
     well).
 
     <AccordionGroup>

diff --git a/static/images/quickstart/phone/outbound/assistant-model-setup.png b/static/images/quickstart/phone/outbound/assistant-model-setup.png
diff --git a/static/images/quickstart/phone/outbound/dial-outbound-call-dashboard.png b/static/images/quickstart/phone/outbound/dial-outbound-call-dashboard.png