Building a Custom API Tool

Custom API tools live under API Tools in the dashboard sidebar. Each tool gets a full-page editor with a request preview and a built-in test panel. For the conceptual overview (what tools can do, correlation headers, value lists), see Custom API Integrations. This article is the build walkthrough.

Creating a tool

1. Go to API Tools in the sidebar
2. Click New tool
3. Fill in the configuration below, then click Create tool (it reads Save changes when you come back to edit)

Start from an example (fastest)

On a new tool, the parameters section opens with a paste box. Drop in the JSON body your API expects (most API docs include one) and the parameter list builds itself, including nested objects and lists. You then add a short guidance note to each field. You can always adjust or add parameters by hand afterwards.

Basic configuration

• Name: what the tool is called (e.g., "Check Appointment Availability")
• Agent instructions: what the tool does and when to use it. Every word of this field is given to the agent as part of the tool's instructions, so write it as directions ("Use this when a caller asks whether a date is open. Ask for the date first."), not as a summary.
• Action type: Look up, Check, Create, Update, Remove, or Notify. Picking one fills in a sensible HTTP method and a default context burden level, both of which you can change.

HTTP configuration

• Method: GET, POST, PUT, PATCH, or DELETE
• URL: the API endpoint. Use {parameter_name} for dynamic values (e.g., https://api.example.com/appointments/{date})
• Timeout: how long to wait for your API, in seconds. Defaults to 10.

Parameters

For each value the agent needs to collect and send:

• Name: the field name your API expects
• Type: Text, Number, True / false, Date, Date & time, Object (group of fields), or a list (of text values, numbers, or objects). Objects and lists of objects can have nested fields; use Paste a sample object (or Paste a sample element for a list) under "Build fields from a sample" to define the shape from one example.
• Where it goes: the unlabeled dropdown next to the type, with Body, Query, Path, or Header
• Guidance for the agent: tells the agent what this value is and how to ask the caller for it
• Req (required): whether the agent must collect this before calling the API
• Allowed values (optional): a fixed list the agent must choose from. Anything else is refused before it reaches your API.

The top-level body must be an object; a bare list or single value at the top level isn't supported.

Authentication

• None: for endpoints that don't need credentials
• API Key: specify the header name (defaults to X-API-Key) and the key value
• Bearer Token: token passed in the Authorization header
• Basic Auth: username and password

Credentials are encrypted at rest and never shown in logs, transcripts, or the dashboard after you save them.

Context burden

Choose how much the agent involves the caller when using this tool: Ambient, Conversational, Requested, Confirmed, or Verified. The action type sets a sensible default. See Understanding Context Burden Levels for what each level means.

Request preview

As you build, the Request preview card shows exactly what the agent will send — method, URL, and an example JSON body — so you can compare it against your API documentation at a glance.

Testing your tool

The test panel lives inside the tool's editor and works once the tool has been saved (it tests what's stored, so save first).

1. Open the tool and scroll to Test this tool
2. Enter sample parameter values (fields with allowed values become dropdowns)
3. Click Run test
4. Review the result: status code, latency, the response body, and the method and URL that were called

Always test before going live. A broken tool means the agent can't complete the action and has to tell the caller it failed.

Common patterns

Calendar/scheduling system: GET availability by date range, POST to book, PATCH to reschedule, DELETE to cancel.

CRM/customer database: GET customer by phone or email, POST to create new record, PATCH to update.

Notification webhook: POST with call data to trigger external workflows (Slack, email, your own automation).

Inventory/availability check: GET product or service availability, return results to caller.