Lesson 4
Handling Inbound and Outbound Numbers
This lesson explains how to manage inbound and outbound numbers within Bland.
LEARNING OBJECTIVES
Purchase and update inbound numbers with POST operations
List and retrieve details of inbound numbers using GET operations
Purchase outbound numbers and list them using POST and GET operations
Management of inbound and outbound numbers is fundamental to smooth and scalable campaigns. In this lesson, you will learn how to add, remove, and assign phone numbers for your conversational pathways.
Inbound Phone Numbers
These are phone numbers that your customers will call into to initiate a conversational pathway. They are offered by Bland on a monthly subscription basis per number.
Request Body Parameters
area_code
Choose a three-digit area code for your phone number. If set as a parameter, a number will only be purchased by exact match if available.
prompt
This defines how the AI will start the conversation, information available to it, and its behaviors. Matches how the outbound task parameter functions.
country_code
Choose a country code for your phone number.
Options: "US" or "CA" for Canada. For others, please contact support.
webhook
The webhook should be a http/https callback url. We will send the call_id and transcript to this URL after the call completes. This can be useful if you want to have real time notifications when calls finish.
phone_number
Specify an exact phone number you’d like to use. If provided, this phone number will override the area_code parameter.
Example of the correct format (note the "+1" is mandatory): "+12223334444"
Responses
Your response JSON will contain the generated phone number for you to reference. This number will be active immediately and available to receive calls.
API: Configuration of Inbound Phone Numbers (POST)
View Documentation
In the creation API request above, you are able to set a “prompt” which is equivalent in function to the “task” parameter of the /simple and /calls endpoints. To use the Conversational Pathways, you’ll need to send an additional request to update your inbound phone number.
Request Body Parameters
pathway_id
The most commonly used parameter, this specifies a Conversational Pathway for your Agent to use. The settings and prompts in your Conversational Pathway will override all the other prompt related parameters you can configure for your inbound phone number.
prompt
(Overridden if you pass a pathway_id)
Provide instructions, relevant information, and examples of the ideal conversation flow. For inbound numbers, consider including additional context about the purpose of the call and what types of callers to expect.
voice
Set your agent’s voice
first_sentence
(Overridden if you pass a pathway_id)
Directs your Agent say a specific phrase or sentence for its first response.
wait_for_greeting
By default, your Agent will start talking as soon as the call connects. Set this to “True” if you want them to wait for the user called to greet them first.
interruption_threshold
Adjusts how patient the AI 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.
The recommended range is from 50 to 200. Start with 100 and make small adjustments in increments of 10 as needed.
model
Select the Bland model to use for the phone calls. You can read about the different models here.
tools
Add your custom created tools to be available for your Agent to use during the call.
Language
Select a supported language of your choice.
timezone
Set the timezone for the call. Handled automatically for calls in the US.
This helps significantly with use cases that rely on appointment setting, scheduling, or having your agent behave differently based on the time of day.
Time zone options are here in the TZ identifier column.
transfer_phone_number
A phone number that the agent can transfer to under specific conditions – such as being asked to speak to a human or supervisor.
Set to “null” to remove.
transfer_list
This gives your agent the ability to transfer calls to a set of phone numbers. If a transfer_list,default is specified, this will override transfer_phone_number—it will default to transfer_list,default or the chosen phone number.
Example usage to route calls to different departments:
"transfer_list": {
"default": "+12223334444",
"sales": "+12223334444",
"support": "+12223334444",
"billing": "+12223334444"
}
dynamic_data
Integrate data from external APIs into your agent’s knowledge.
keywords
These words will be boosted in the transcription engine -- recommended for proper nouns or words that are frequently mis-transcribed.
For example, if the name “Reece” is frequently transcribed as “Reese” you could do this:
{
"keywords": ["Reece:3"]
}
/// for stronger keywords, you can use the 'boost factor' set to three in this ///example
Responses
status
Whether the update was successful or not -- will be success or error.
message
A message describing the status of the update.
updates
An object containing the updated settings for the inbound number.
Module 2 Conclusion
After completing Module 2, you should now be able to perform the foundational actions needed for building great phone Agents. You can now:
Make basic calls with prompts (via the web and Bland API)
Create and manage your vector stores of information for your Agent to use
Create and understand basic Conversational Pathways
Create and manage inbound phone numbers
What’s Coming Next?
Conversational Pathways give you the flexibility to construct elegant and fully functional designs for your Agents to follow. They are infinitely scalable, and come packed with additional tools to control your Agent’s flow as well as interact with the outside world.
%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)