> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brosbots.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom integrations (wizard)

> Connect the agent to any system: calls to your API during the conversation, event webhooks and leads from forms.

When your system is not in the catalog, build the integration yourself in a
step-by-step wizard: **Integrations** → **Custom** tab. No JSON or code
needed, just the API address and (usually) a key.

The wizard builds three kinds of integration:

| Kind | What it does | Example |
| - | - | - |
| **During the call** | the agent calls your API when the caller asks for something and reads the answer | "Where is my parcel?" → the agent checks the status in your store |
| **Notify on an event** | we send a signed message to your address after a call, an SMS, a campaign | a CRM entry through n8n after every call |
| **Leads from forms** | a website form sends a lead and the agent calls back straight away | contact form → a phone call within seconds |

## During the call

Start from the **From scratch** tile or from a template:

* **Order status** - the agent asks for the order number and reads the status
  and delivery date,
* **Save lead to CRM** - the agent saves the caller's name, phone and request,
* **Free slots** - the agent checks the free times on a given day.

A template fills in everything except your API's address. The wizard has six
steps.

### 1. Purpose

Name and description. **The agent reads the description** to decide when to
use the integration, so be specific, as if briefing a new colleague: what it
checks and what the agent should tell the caller afterwards.

### 2. Connection

Method (`GET`, `POST`…), address and optional headers.

* **Paste cURL**: a `curl` command from the API docs fills in the method,
  address, headers and fields. A token from `Authorization: Bearer` and a
  login from `-u` become a stored key.
* **API sign-in**: pick a stored key or add one (Bearer token, API key in a
  header, username and password, custom header). Keys are stored encrypted.
* The address and headers can use call data: `{{caller_number}}` (the
  caller's number), `{{called_number}}`, `{{direction}}` and any call
  variable. The caller's number does not need to be a field the agent asks for.

### 3. Caller data

What the agent asks before sending the request. Each field has a name
(letters, digits and `_`), a type and a description for the agent.

| Type | What your API receives |
| - | - |
| Text | text |
| Number | a number |
| Yes / no | `true` / `false` |
| Date | text `YYYY-MM-DD` |
| Phone | text such as `+48600100200` |

For `POST`, `PUT` and `PATCH` the fields go in the body as JSON; for `GET`
and `DELETE` as query parameters.

### 4. Test

Sends a real request with sample values, **without saving**. You see the
request sent (the key is masked) and your API's response, and tick the
response fields the agent should read.

### 5. Response

* **What the agent says while waiting** - e.g. "One moment, checking". Empty:
  the general phrase from the agent's settings.
* **Response fields for the agent** - dotted paths such as `order.status` or
  `items.0.name`. The agent gets only these: it answers faster and does not
  improvise from fields that mean nothing to the caller. When none of the
  paths is in the response (the API changed), the agent gets all of it.
* **What to say when the system does not answer** - the sentence the agent
  says on an error or a timeout.
* **Longest wait** - 3 to 10 seconds.

### 6. Agents

* **When the caller says…** - example sentences after which the agent should
  use the integration. It recognises similar ones too.
* **Which agents** - tick the agents. Takes effect from the next call.

Edit the integration later in the same wizard. **Advanced** opens the full
tool editor ([Tools](/en/voice-agent/tools)).

## Notify on an event

A webhook with signed events: `call.completed`, `call.started`,
`sms.received`, `campaign.completed`, `balance.low`, `lead.dropped`, with agent selection and
a test. Details and signature checks: [Webhooks](/en/integrations/webhooks).

## Leads from forms

A four-step wizard gives the agent an address for your form:

1. **Agent** - which agent calls back. Ideally one from the **Lead Callback**
   template.
2. **Settings** - calling hours and days, the phone field name (usually
   empty: we find it ourselves), country code, ignoring repeats.
3. **Test** - paste a sample submission (JSON, or `field: value` lines from
   the form's email). **Nobody gets called**: you see the number, the fields
   and when the agent would call.
4. **Address** - **Switch on and show the address** turns leads on for the
   agent and shows the address to paste into the form, a cURL command, and
   the URL with key for Google Ads lead forms.

The agent does not need a **Lead webhook** node in its flow beforehand: the
wizard adds it. What data is accepted and what the responses mean:
[Lead callback from a form](/en/integrations/leads/lead-webhook).

## Security

* API keys and webhook signing keys are stored encrypted and never returned
  in full by the API.
* Private-network addresses and `localhost` are blocked, both for requests
  during the call and for webhooks.
* The lead address contains a key: paste it on the server side or in your
  form tool's settings, not in the page's code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.