Ask a Human

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:

{
  "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:

{
  "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.

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.

Start here

Personal assistants

Configure

Test

Deploy

Common jobs

Campaigns

Monitor

Fix a problem

Accounts and workspaces

Good to know

What it does

Turn it on for a call

What the person hears

What can go wrong

What you get back

FAQ

​What it does

​Turn it on for a call

​What the person hears

​What can go wrong

​What you get back

​FAQ

​Related

What it does

Turn it on for a call

What the person hears

What can go wrong

What you get back

FAQ

Related