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

# Ask a Human

> Let your agent phone a person in the middle of a call when it is asked for something it does not know, get the answer, and carry on. Turn it on per call from the API.

Ask a Human lets your agent phone a person when the other side of a call asks for something it does not
know. The agent puts the other side on hold, rings the person, gets the answer, and comes back to finish
the call itself. You turn it on for one call at a time from the API, with `agent_overrides.ask_a_human`.

## What it does

Two examples.

**A personal agent.** You tell your agent: "Call Xfinity and dispute the late fee. If they need anything
from me, ask me." The Xfinity rep asks for your date of birth. The agent says "One moment, let me check
with Harvey" and puts the rep on hold. Harvey's phone rings: "Brilo here, I'm on the phone with
+1 800 934 6489. They're asking: what is your date of birth?" He answers. The agent comes back: "Thanks
for holding, the date of birth is March 3rd 1990."

**A business.** A clinic's agent calls an insurer through the API to verify coverage. The insurer asks for
the group number. The agent rings the clinic's front desk, the number passed as `phone_number` on the
call, and comes back with the answer. If the front desk says "put me on the call", they are merged into
the call as a normal transfer.

While the other side waits, the agent plays hold music and says "Still checking, thanks for waiting"
every 30 seconds.

## Turn it on for a call

Add `ask_a_human` inside `agent_overrides` on [`POST /v1/call`](https://docs.brilo.ai/api-reference/endpoint/call):

```json theme={null}
{
  "agent_id": "...",
  "to": "+18009346489",
  "agent_overrides": {
    "instruction": "Call Xfinity and dispute the $40 late fee on my account. If they need anything from me, ask me.",
    "greeting": "Hi, I'm calling on behalf of Harvey about a late fee on his account.",
    "ask_a_human": {
      "enabled": true,
      "when": "They ask for my date of birth, account PIN, or want to speak to the account holder"
    }
  }
}
```

| Field | Required | What to send |
| - | - | - |
| `enabled` | Yes | `true` to turn it on for this call, `false` to leave it off. |
| `when` | Yes, when enabled | When the agent should phone the person, 1 to 500 characters. It is shown to the agent after a fixed instruction to ask instead of guessing. |
| `channel` | No | Defaults to `phone`, the only channel for now. `chat` and `chat_then_phone` are reserved for later and return `ask_a_human_channel_unavailable`. |
| `can_join` | No | Defaults to `true`. When `true`, the person can say "put me on the call" and be merged in. When `false`, the agent cannot connect them. |
| `phone_number` | Business plans only, required there | Who to ring, in E.164 format such as `+15551234567`. Not allowed on the Agent Phone Plan. |
| `human_label` | Business plans only, optional | What the agent calls the person, such as "the front desk". 1 to 60 characters. Defaults to "a colleague". On the Agent Phone Plan the agent uses the owner's first name. |

Ask a Human works for personal and business agents:

* **On the Agent Phone Plan**, the agent always rings the account owner's verified phone. Do not send
  `phone_number` or `human_label`. If the owner has no verified phone on their Brilo account, the call is
  refused with `owner_phone_missing`.
* **On a business plan**, send the `phone_number` to ring. It must be a number Brilo can call, in a
  supported country.

Only one ask is in flight at a time on a call. An agent can ask more than once in the same call.

## What the person hears

Every ask starts by saying who is asking: "Brilo here, I'm on the phone with +1 800 934 6489. They're
asking: ..." The person always knows which call this is about.

If the question is for a code, PIN or password, the agent adds: "Only share this if you started this call
and trust them." Someone who did not start the call should not read a one time code to a stranger, and
this line gives them the moment to stop.

The agent reads the answer back once ("So that's March 3rd 1990?") before it returns to the other side.

## What can go wrong

Every refusal carries a `code`, a `message` and an `action`, so a caller can tell what happened and what
to do next. All are `400` unless noted.

| Code | When | What to do |
| - | - | - |
| `ask_a_human_channel_unavailable` | `channel` is `chat` or `chat_then_phone`. | Remove `channel` or set it to `phone`. |
| `ask_a_human_number_locked` | `phone_number` or `human_label` was sent on the Agent Phone Plan. | Remove them. On the Agent Phone Plan the agent always calls the account owner's verified phone. |
| `ask_a_human_number_required` | A business plan call has no `phone_number`. | Add `phone_number` in E.164 format. |
| `ask_a_human_workflow_unsupported` | The agent runs a workflow. | Remove `ask_a_human`, or use an agent that has no workflow. |
| `destination_not_supported` | The business `phone_number` is outside the countries your plan can call. | Use a number in a supported country. |
| `owner_phone_missing` | Agent Phone Plan, and the owner has no verified phone on their Brilo account. | Add and verify a phone number on the Brilo account, then send the call again. |
| `owner_phone_lookup_failed` | `503`. Brilo could not look up the owner's phone just now. | Send the call again in a few seconds. This one is safe to retry. |

A body that is the wrong shape, such as a missing `when` or an unknown key, returns a plain `400` that names
the field.

## What you get back

`GET /v1/call/{id}` includes an `ask_a_human` list with one entry for each ask the agent made:

```json theme={null}
{
  "ask_a_human": [
    { "question": "What is your date of birth?", "outcome": "answered", "at": "2026-10-07T10:00:05.000Z" }
  ]
}
```

It is an empty list for a call that never asked. The `outcome` is one of:

| Outcome | Meaning |
| - | - |
| `answered` | The person gave an answer and the agent carried on. |
| `joined` | The person asked to be put on the call and was merged in. |
| `no_answer` | The person did not pick up. |
| `voicemail` | The ring went to voicemail. |
| `declined` | The person said they could not or would not help. |
| `other_side_hung_up` | The other side hung up while the agent was asking. |
| `failed` | The call to the person could not be completed, or they were busy on another ask. |
| `unavailable` | The agent was meant to be able to ask but the tool could not be set up for this call. |

The list never contains the answer. Outcomes can take a few seconds to appear after the call ends.

> [!WARNING]
>
> Answers you give are in the call transcript. Recording is off on the Agent Phone Plan, but transcripts
> are stored, so a date of birth you say on the phone is part of the transcript of that call.

## FAQ

> **Does Ask a Human work for personal agents and business agents?**
>
> Yes, both. On the Agent Phone Plan the agent rings the account owner's verified phone. On a business
> plan you pass the `phone_number` to ring, for example the front desk. The fields differ, but the call
> works the same way.

> **Why was my call refused with ask\_a\_human\_number\_locked?**
>
> You sent `phone_number` or `human_label` on the Agent Phone Plan. On that plan the agent always calls the
> account owner's verified phone, so those fields are not accepted. Remove them and send the call again.

> **Can the agent ask me through chat instead of a phone call?**
>
> Not yet. `chat` and `chat_then_phone` are reserved, and sending them returns
> `ask_a_human_channel_unavailable`. Only the phone channel works today.

> **Can the person take over the call?**
>
> Yes, unless you set `can_join` to `false`. The person says "put me on the call" and is merged into the
> call as a normal warm transfer. With `can_join` off, the agent has no way to connect them.

> **Is the answer stored anywhere?**
>
> The answer is in the call transcript, like anything else said on the call. It is never in the
> `ask_a_human` list on the call result or in the call's events. Recording is off on the Agent Phone Plan,
> so there is no audio of it there.

> **How many times can the agent ask in one call?**
>
> As many times as it needs, one at a time. There is no cap on the number of asks, so write a clear `when`
> to keep the agent from phoning the person for things it could handle itself.

## Related

* [Per-call agent overrides](https://docs.brilo.ai/api-reference/endpoint/call.md)
* [Setup steps for your assistant](https://docs.brilo.ai/personal-assistants/connect.md)
* [Pass the call to a person](https://docs.brilo.ai/actions/pass-the-call-to-a-person.md)
* [When a caller asks for a person](https://docs.brilo.ai/calls/when-a-caller-asks-for-a-person.md)


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