In this starter guide, we’ll describe how to send your first phone call, then how to iterate on it and send even better ones.

At a high level, all our API requires is a phone number to call and a task for our AI. Then, we handle the entire end-to-end phone call. In other words, you just send us instructions, and then our AI phone agent handles the entire phone call. It’s our job to build a great AI phone agent; it’s your job to provide super clear instructions.

Let’s get started!

Making an awesome prompt

Great prompts include the following:

  1. A clear goal for the phone call
  2. A clear sequence of events that should unfold (i.e. explain what should happen at each stage of the phone call)
  3. Tons of context about why the phone call is occurring
  4. Background information about the AI phone agent’s “character”
  5. DIALOGUE EXAMPLES (absolutely the most important element for getting great outputs from prompts)

Example prompt

Here’s a prompt for a telehealth reminder phone call:

Your name is James and you’re a health assistant at Nutriva Health. After patients create an appointment, right before the appointment date, you send check-in calls. If a patient misses the appointment, your company loses lots of revenue. It’s vital that the patient shows > up or reschedules to a more convenient time. Either works.

Here’s an example dialogue

Person: Hello? You: Hey is this Jessica? My name is James, I’m a health assistant from Nutriva Health. I wanted to check in with you about your upcoming appointment. Person: Oh, hi James. Great to meet you. How can I help? You: Hey Jessica, great to meet you too. I just wanted to confirm that you’ll attend your upcoming appointment? Or if it not longer fits your schedule, I wanted to help you find another time. Person: Gotcha, this was actually the perfect call. I just realized I’m going to need to go to the office tomorrow morning for a big client meeting. I’d love to reschedule to next week if possible? You: Yeah absolutely. What timing is convenient for you? Person: Ummm, maybe Wednesday? Any time in the afternoon. You: Perfect, I’ve noted that information down. Another member of our team will reach out shortly. Person: Ok, thank you! You: Of course, have a great day! Goodbye.

Sending your first phone call

To send phone calls using a visual interface, check out the Bland AI developer portal.

Otherwise, here’s a code example that you can run from within your IDE. Aside from the prompt and phone number fields, we also allow users to pass:

  1. A voice ID (which relates to different voices we provide access to)
  2. Request data (you can pass tons of extra data about the people you’re calling, here)
  3. Reduce latency mode, for lower-quality voices that generate faster
  4. AMD mode, for navigating phone trees & IVR systems
  5. A Webhook to POST data to at the end of each phone call

Most of these settings will be irrelevant though. The prompt is 90% of the battle. Everything else can easily be tweaked.

Here’s a code example:

curl -X POST "" \
     -H "Authorization: YOUR-API-KEY-HERE" \
     -H "Content-Type: application/json" \
     -d '{
           "phone_number": "7778889999",
           "task": "You are calling Fantastic Airlines on behalf of John Doe. Find out where Johns Bags are located.",
           "voice_id": 0,
           "request_data": {
             "calling": "Fantastic Airlines",
             "bag_claim": "69683",
             "airline_code": "UA123"
           "reduce_latency": true,
           "amd": true,
           "webhook": "YOUR-WEBHOOK-HERE"

Testing and iterating

Once you’ve narrowed down your use case, and you’re looking to test and optimize your AI phone calling agent, it’s a simple matter of sending phone calls and tweaking your prompt.

To make testing easier, you can use our agent testing tool. Insert your current prompt, then chat with the AI. When you notice an output you dislike, update the prompt to account for it. Similarly, update the example dialogue in the prompt to show how the AI could better respond to the query.

If you ever, at all, start struggling with making a great prompt, jump into our discord community to get help from other Bland AI users.