Lesson 4
Advanced Call and Batch Operations
This lesson delves into advanced call and batch operations, including batch analysis and management.
Learning Objectives:
Send and manage batches of calls using POST operations
Analyze batches with AI and stop active batches using POST operations
List batches and retrieve batch details with GET operations
Batch call operations can give you two pieces of great functionality for large call volumes.
1
Sending a large number of calls with a simple prompt (Simple Batch)
2
Initiating a large-scale “campaign” (Campaign Batch)
Making a Simple Batch Call via Bland API
Request Header
Standard Bland Authorization Header and Content-Type of application/json
Content-Type: application/json
Authorization: [API Token]
Request Body
base_prompt
This is the prompt or task used for all the phone calls in the request. Information can be inserted by surrounding variable names with {{curly braces}}.
call_data
This holds the list of each call to be made in your batch.. Each call in call_data MUST have a “phone_number” property. Properties are case-sensitive.
from
The phone number to originate the calls from.
label
Adds a user-friendly label to your batch to keep track of it’s original intended use. This can help differentiate multiple call batches that are part of the same campaign. Shown when a batch is retrieved.
campaign_id
This will be used for starting batch calls within a more complex campaign (including pathways).
test_mode
(true/false) Includes additional information in the response to make any issues easier to find.
Let’s look at an example request body and Postman request:
{
base_prompt: "You are calling {{business}} to renew their subscription to {{service}} before it expires on {{date}}.",
"from": "1238889784",
"label": "Renewal agent Batch Call",
"call_data":
[
{
"phone_number": "1234567890",
"business": "ABC Corp",
"service": "Netflix",
"date": "September 4th"
},
{
"phone_number": "32176540987",
"business": "XYZ inc.",
"service": "Window Cleaning",
"date": "December 20th"
}
]
}
Analyzing Your Batch Calls With AI
This enables you to assess whether or not your batch calls are working as intended and to pull out insights from ongoing calls. This is also done via the Bland REST API.
Please note:
You can set your “from” number in the API request. This will need to be a number owned by that Twilio account (and not one purchased through Bland).
If a “from” is not specified a number listed in the specified Twilio account will be randomly selected..
Request Header
Standard Bland Authorization Header and Content-Type of application/json
Content-Type: application/json
Authorization: [API Token]
Request Header
In your URL Path, you will specify the specific batch_id you want to assess.
Request Body
Goal
This is the overall purpose of the batch of calls. Provides context for the analysis to guide how the questions/transcripts are interpreted.
questions
This is a list of lists. Each question should be an array with two elements: the question text and the expected answer type (e.g., “string,” “boolean”).
Fairly flexible in terms of the expected answer type, and unanswerable questions will default to null.
"questions": [
["Who answered the call?", "human or voicemail"],
["Positive feedback about the product: ", "string"],
["Negative feedback about the product: ", "string"],
["Customer confirmed they were satisfied", "boolean"]
]
Response
status
Will say “success” if the request was successful.
message
Confirms the request was successful or provides an error message if the request failed.
answers
Contains the analyzed answers for each call in the batch.
The keys are call_ids from the batch, and the array values are the analysis results for each question in the batch. You’ll be able to derive your insight from these results. They can also be passed on to your own sentiment analysis model for creating indicators.
credits_used
Token-based price for the analysis request.
As a rough estimate, the base cost is 0.003 credits with an additional 0.0015 credits per call in the batch.
Longer call transcripts and higher numbers of questions can increase the cost. However, note that the cost scales more economically with batches compared to individual calls.
Example From Postman
Batch Call Details (REST API)
Batch details requests contain a massive amount of data on all calls performed during a single batch. To read the individual responses, please see the API documentation. We’ll learn how to assess these results in the next module.
Campaigns and Batch Calls
Campaigns are a powerful tool for creating multi-call workflows. In addition to allowing you to schedule multiple calls and manipulate timing (such as having the agent wait a day before calling back), you are also able to assign Conversational Pathways to be run for the calls.
Create Your First Campaign
The “Create Campaign” button can be found on the dashboard. .
Batch Label
Descriptive label to keep track of your campaign.
Encrypted Key BYOT
This is an API key to your Twilio account.
Call Data
This is where you upload a CSV file. The first row should contain the headers of the table.
Note: The headers should not include any special characters other than hyphens (-) or underscores (_). The column containing phone numbers must have a header labeled as "phone_number."
Prompt
You can enter a prompt for your calls here. Alternatively, you can leave this blank and assign a Conversational Pathway for your batch calls to follow.
Model
Select one of the three Bland models.
Language
The language your call will be made in.
Voice
Choose a voice from our library of voice models.
Temperature
A value between 0 and 1 that controls the randomness of the LLM. 0 will create more deterministic outputs; 1 will create more random ones.
Interruption Threshold
Adjusts how patient the agent is when waiting for the user to finish speaking.
Lower values mean the AI will respond more quickly, while higher values mean the AI will wait longer before responding.
Recommended range: 50-200
50: Extremely quick, back and forth conversation
100: Balanced to respond at a natural pace
200: Very patient, allows for long pauses and interruptions. Ideal for collecting detailed information.
Try to start with 100 and make small adjustments in increments of ~10 as needed for your use case.
Start Time
Specify when the campaign will begin.
Transfer Number and List
If transfer numbers have not already been specified in your conversational pathway, use these fields to assign numbers for your agent to transfer calls to during the execution of the campaign.
Meta Data
Key-Value pairs you can use to help track and aggregate data from multiple campaigns later on. This will be covered in more detail in the next module.
Pronunciation Guide
Sometimes it may be necessary to specify the pronunciation of certain words, especially if you’re operating in a niche industry that is jargon-heavy. You can use this section to teach your agents how to say any word.
Post Call Webhook
When the call ends, the call details will be sent in a POST request to the URL you specify here.
Voicemail Action
This is processed separately from the AI’s decision making and overrides it. The options are:
hangup
leave_message
ignore
Note: that if voicemail_message is set, then the AI will leave the message regardless of the voicemail_action.
Voicemail Message
When the AI encounters a voicemail, it will leave this message after the beep and then immediately end the call.
Note: that if amd is set to “true” or voicemail_action is set to “ignore,” then this will still work for voicemails, but it will not hang up for IVR systems.
%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20stroke-width%3D%2216%22%2F%3E%3Cpolyline%20points%3D%2256%20112%20128%2040%20200%20112%22%20fill%3D%22none%22%20stroke%3D%22rgb(255%2C%20255%2C%20255)%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20stroke-width%3D%2216%22%2F%3E%3C%2Fsvg%3E%0A)