Set up inbound calls & caller matching

What are the inbound calling settings?

Inbound settings live in the Calling tab of your agent, under the Inbound Calling toggle (the standalone Inbound tab has been merged into Calling). Toggle it on to pick an inbound number, match callers to your database, preload user data before the call starts, and set up spam prevention to protect your agents from abuse.

Inbound Calling section toggled on, showing Inbound number selector, Database for inbound phone numbers, and Spam Prevention Settings — Inbound Calling section in the Calling tab

Open the Calling tab

Select your agent in Agent Studio and open the Calling tab.

Toggle on Inbound Calling

Switch on Inbound Calling and pick an Inbound number from your phone numbers. The database and spam settings below unlock once a number is selected.

Save agent

Click Save agent for the inbound number to take effect.

Database for inbound phone numbers

Match incoming calls to users and preload their data before the call starts. The Select data source dropdown stays disabled until an inbound number is selected; once it is enabled, choose from three data source options:

Internal APIs
CSV Upload
Google Sheet

Connect your own API to fetch user data dynamically when a call comes in. Selecting this option reveals an Enter API Endpoint URL field and an Enter Auth Token field beside the data source dropdown.

Select Data Source

Choose “Use your internal APIs” from the dropdown.

Enter API Endpoint URL

Provide your API endpoint that will receive the caller data request.

Add Auth Token

Enter your Bearer token for secure authentication.

Query Parameters

Bolna automatically passes these parameters to your API:

Parameter	Description
`contact_number`	The caller’s phone number
`agent_id`	Your agent’s identifier
`execution_id`	Unique identifier for this call

Your API must return a JSON response with user details. Bolna will inject this data directly into your agent’s prompt for personalized conversations.

Example API Request

curl -X GET "https://your-api.com/user-data?contact_number=+919876543210&agent_id=abc123&execution_id=xyz789" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json"

Example API Response

{
  "user_name": "John Doe",
  "account_status": "premium",
  "last_purchase": "2026-01-15"
}

Authentication uses Bearer token and is stored securely by Bolna.

Upload a CSV file containing your user database. Selecting this option reveals an Upload CSV File button beside the data source dropdown.

Select Data Source

Choose “Use a CSV” from the dropdown.

Upload CSV File

Click Upload CSV File and select your file.

The CSV file must include a contact_number column containing phone numbers. These numbers will be matched against the caller’s phone number.

CSV Format Example

contact_number,user_name,account_type
+919876543210,John Doe,premium
+918765432109,Jane Smith,basic

Connect a public Google Sheet as your user database. Selecting this option reveals a Google Sheet URL field and a sheet name field beside the data source dropdown.

Select Data Source

Choose “Use a public Google Sheet” from the dropdown.

Enter Google Sheet URL

Paste the URL of your public Google Sheet.

Enter Sheet Name

Specify the exact name of the sheet tab to use.

The sheet must be public and should include a contact_number column containing phone numbers.

Call restrictions

Toggle on Allow incoming phone calls only from the chosen database to restrict incoming calls to phone numbers found in your chosen database. Unknown callers will be rejected.

Spam prevention settings

Protect your agent from spam and abuse.

Setting	Description
Maximum calls allowed per Phone Number	Limit calls from a single number. Set to `-1` for unlimited.
Always-allow list (bypass call limits)	Phone numbers that bypass all call limits.

Add your support team and VIP customers to the always-allow list to ensure they’re never blocked.

Use cases

Customer verification

Only allow calls from registered customers

VIP support

Preload customer data for personalized service

Abuse prevention

Limit repeated calls from the same number

Dynamic data loading

Fetch real-time customer data via API

Next steps

Agent tab

Configure prompts and welcome message

Calling tab

Set up telephony and call features

Receiving calls guide

Complete inbound setup guide

Phone numbers

Purchase and manage phone numbers

Build

Deploy

Monitor

Go live

Set up inbound calls & caller matching

What are the inbound calling settings?

Database for inbound phone numbers

Query Parameters

Example API Request

Example API Response

CSV Format Example

Call restrictions

Spam prevention settings

Use cases

Customer verification

VIP support

Abuse prevention

Dynamic data loading

Next steps

Agent tab

Calling tab

Receiving calls guide

Phone numbers

​What are the inbound calling settings?

​Database for inbound phone numbers

​Query Parameters

​Example API Request

​Example API Response

​CSV Format Example

​Call restrictions

​Spam prevention settings

​Use cases

Customer verification

VIP support

Abuse prevention

Dynamic data loading

​Next steps

Agent tab

Calling tab

Receiving calls guide

Phone numbers

What are the inbound calling settings?

Database for inbound phone numbers

Query Parameters

Example API Request

Example API Response

CSV Format Example

Call restrictions

Spam prevention settings

Use cases

Next steps