Custom API Integration

Introduction

To call your own API during a conversation, build a webhook tool. Use one when:

You have your own backend API you want to call during calls
You’re integrating with a third-party service that isn’t in the built-in list
You need custom request formatting, headers, or authentication

This tutorial builds a tool that saves a call summary with Bland’s Create Prompt endpoint. By the end, you’ll know how to:

Store an API key as a secret and reference it
Write a request with variables the agent fills in
Capture data from the response
Tag the tool into an agent’s prompt and use what it returns

For the full builder reference, see Build a webhook tool.

Prerequisites

An agent to tag the tool into, from Agent builder
Your Bland API key

Step 1: Store your API key as a secret

Do not paste an API key into a tool. Set the sidebar selector to All agents, open Tools, and on the Secrets tab click Add Secret. Name it something like bland_api_key and paste your key as a Static secret. See Secrets for details.

Step 2: Create the tool

From inside your agent, open Tools, click Create tool, and choose Webhook. If you already have a working curl command, choose Import from cURL instead. It opens the builder with the request filled in.

Step 3: Name and describe it

Name. The name is what you type after @ in a prompt. Make it the thing the tool does: “Save call summary” reads better than “POST request”. Description. The agent reads this to decide when to call the tool. Write the trigger:

Save a summary of the call. Use this once the caller has finished
describing their request and before you wrap up.

Agent speech. What the agent says while the tool runs, like “One moment while I save that.” It keeps the caller from hearing dead air.

Step 4: Configure the request

Method and URL. Choose POST and enter https://api.bland.ai/v1/prompts.

Webhook tools run GET and POST only. The method list shows other verbs, but a tool using one of them fails to save with Failed to create tool.

Authorization. On the Authorization tab, choose API Key. Set Header name to authorization, which is the header the Bland API expects, and pick your bland_api_key secret. Body. Write the request body. Anywhere a value should change per call, write a variable:

{
  "name": "{{caller_name}}",
  "prompt": "{{call_summary}}"
}

Add any other headers your API needs on the Headers tab.

Step 5: Say which variables the agent fills in

The variables you wrote are listed under Detected variables. For each one, click Add input variable so the agent fills it from the conversation. Then give it instructions, a type, and whether it is required:

Variable	Instructions
`caller_name`	The caller’s full name.
`call_summary`	A short summary of the key points discussed in this call.

Write instructions for a person. Be specific about the format when it matters. A variable you leave alone resolves from variables already on the call instead, and the agent never fills it.

Step 6: Declare what comes back

Output fields name the parts of the response the agent can use. They start with ok, message, and data, with ok and message checked. Keep ok checked: a failed call returns only ok and message. For a POST tool, the response fields under data are named rest_api_post_*:

Field	What it holds
`rest_api_post_status`	The HTTP status
`rest_api_post_status_text`	The status text
`rest_api_post_data`	The response body from your endpoint

The builder lists these as rest_api_get_* until the tool is saved. Save it, reopen it, and check the rest_api_post_* rows then. To pull one value out of the response body, add a row with a name and a JSONPath. For the prompt ID, add a row named prompt_id with the path $.data.rest_api_post_data.prompt.id.

Checking at least one output field is what makes the tool wait for a response. Check nothing and the tool fires and moves on.

Run the tool with sample values and check the response before you attach it to anything.

Step 7: Tag the tool into a prompt

Building the tool does not give it to the agent. In the agent’s Prompt, type @ and pick Save call summary. The tool then appears under Tool references. Use the tool’s outputs in the same prompt by their bare names:

When the caller is done, use @Save call summary. If {{ok}} is true,
tell the caller their reference ID is {{prompt_id}}. If not, apologize
and let them know a teammate will follow up.

If the step that needs the tool lives in its own pathway, tag the tool in that pathway’s prompt too. Tools do not follow the agent into pathways. See Tag a tool into a prompt.

Additional settings

These sit below the output fields:

Timeout: how long to wait before giving up, from 1,000 to 60,000 milliseconds.
Cooldown: the minimum gap between calls, from 1 to 30 seconds.

Docs for agents: llms.txt

Getting started

Build

Monitor

Dispatch

Configure

Validate

Support

AI Agents & MCP

Platform Information

Bland Enterprise

Legacy

Custom API Integration

Introduction

Prerequisites

Step 1: Store your API key as a secret

Step 2: Create the tool

Step 3: Name and describe it

Step 4: Configure the request

Step 5: Say which variables the agent fills in

Step 6: Declare what comes back

Step 7: Tag the tool into a prompt

Additional settings

​Introduction

​Prerequisites

​Step 1: Store your API key as a secret

​Step 2: Create the tool

​Step 3: Name and describe it

​Step 4: Configure the request

​Step 5: Say which variables the agent fills in

​Step 6: Declare what comes back

​Step 7: Tag the tool into a prompt

​Additional settings

Introduction

Prerequisites

Step 1: Store your API key as a secret

Step 2: Create the tool

Step 3: Name and describe it

Step 4: Configure the request

Step 5: Say which variables the agent fills in

Step 6: Declare what comes back

Step 7: Tag the tool into a prompt

Additional settings