Setup steps for your assistant

This page is written for AI assistants. Setting this up yourself? Go to Give your assistant a phone number and copy the prompt.

Follow these steps to get your own Brilo phone number and an API key. Your owner approves and pays in their own browser; you never handle payment. At the end you receive api_key, phone_number and agent_id, and you can place calls from that number and read the calls people make to it.

Rules

Never pay, sign up or approve anything for your owner.
Keep device_code and api_key out of the chat, logs, URLs and source files.
approved does not mean done. It means your owner has paid and the number is still being set up. Keep checking until status is completed.
Every response has message and action in plain English. Follow action.

1. Start

No API key is needed. Send your own product name as client_name (up to 64 characters). If you know your owner’s name, email or phone number, pass them in prefill so their sign-up form arrives filled in. Values that are not usable are dropped silently, and Brilo does not store them.

curl -X POST https://api.brilo.ai/v1/agent/onboarding/start \
  -H "Content-Type: application/json" \
  -d '{"client_name": "Meta Muse",
       "prefill": {"first_name": "Maya", "last_name": "Chen",
                   "email": "maya@example.com", "phone": "+14155550123"}}'

{
  "device_code": "<device_code>",
  "user_code": "<user_code>",
  "verification_url": "https://dashboard.brilo.ai/agent-setup",
  "verification_url_complete": "https://dashboard.brilo.ai/agent-setup?code=<user_code>#first_name=Maya&last_name=Chen&email=maya%40example.com&phone=%2B14155550123",
  "expires_in": 900,
  "interval": 5,
  "message": "Pairing started. Your owner signs up, pays and approves on the link.",
  "action": "Send owner_message to your owner exactly as written. ...",
  "owner_message": "Here's your link: https://dashboard.brilo.ai/agent-setup?code=<user_code>#first_name=Maya&last_name=Chen&email=maya%40example.com&phone=%2B14155550123\nYour code: <user_code>\nSign up and pay on that page. The code should match. It lasts 15 minutes."
}

Every <...> above stands for a value in your own response. Never send or reuse an example value.

2. Show your owner the link and the code

Send owner_message from the step 1 response, exactly as written, with the link tappable. It already has the link with the code built in (verification_url_complete) and the code on its own line, so your owner can check it matches the page:

Here's your link: https://dashboard.brilo.ai/agent-setup?code=<user_code>#...
Your code: <user_code>
Sign up and pay on that page. The code should match. It lasts 15 minutes.

<user_code> stands for the code in your own response. Never send a code from this page: every code on it is an example, and your owner’s page will not accept it. Do not build your own message from verification_url: it has no code in it, so your owner would have to type the code by hand. If you start a new pairing (for example after a code expires), send the new owner_message. If you cannot send links, read out verification_url and the code instead. Do not open the link yourself: the page is for your owner.

3. Check until it is done

Call POST /v1/agent/onboarding/poll with the device_code, waiting at least interval seconds between calls. If you cannot keep checking on your own (for example, you only act when your owner messages you), tell your owner: “Tell me when you’ve finished paying.” Then check once when they do.

curl -X POST https://api.brilo.ai/v1/agent/onboarding/poll \
  -H "Content-Type: application/json" \
  -d '{"device_code": "<device_code>"}'

`status`	What it means	What to do
`pending`	Your owner has not finished yet.	Keep checking. If they ask, their code is still waiting.
`payment_failed`	The card was declined. The same code still works.	Keep checking. Tell them they can try another card on the page they have open.
`approved`, `provisioning`	Paid. The number is being set up.	Keep checking. This usually takes under a minute. If it is still setting up after 10 minutes, stop and tell your owner Brilo is finishing their setup.
`completed`	Done. This response carries your key.	Store `api_key` in secret storage and stop checking.
`denied`	Your owner said no.	Stop. Do not start again unless they ask.
`expired`	The 15 minutes ran out before they paid.	Stop. Start again only if they still want it.
`failed`	Setup could not finish. It is not your owner’s fault.	Stop and tell them Brilo will be in touch.

Checking faster than interval returns a 429 that says how long to wait, in the body and in the Retry-After header. Wait that long, then continue.

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "code": "slow_down",
  "message": "You are checking too often.",
  "action": "Wait 10 seconds, then check again.",
  "retry_after": 10
}

4. Save your key

{
  "status": "completed",
  "message": "Pairing complete. This API key is ready to use.",
  "api_key": "sk_...",
  "workspace_id": "...",
  "phone_number": "+14155550199",
  "agent_id": "...",
  "limits": {
    "concurrent_calls": 1,
    "max_call_minutes": 60,
    "calls_per_hour": 20,
    "calls_per_day": 100,
    "call_minutes_per_day": 600,
    "calls_per_destination_per_day": 10
  }
}

If your connection drops, check again: a completed pairing returns the same key. If the response has code: pairing_key_replaced, this pairing’s key is no longer active; start a new pairing only if your owner asks you to. Then tell your owner their new number.

5. Remember that you can make calls

Save a note in your long-term memory, custom instructions or notes file (whatever you keep across chats), so that in any later conversation you know you can make and check phone calls for your owner. Replace each <...> with the value from the step 4 response; do not copy the placeholders. Never put the key itself in the note:

I can make and check phone calls for my owner with Brilo.
- My Brilo number: <phone_number>. My agent_id: <agent_id>. My Brilo key is in my secure storage.
- To call someone: POST https://api.brilo.ai/v1/call. How to write the call:
  https://docs.brilo.ai/personal-assistants/connect.md
- Ready-made calls (phone menus, hold, voicemail, businesses):
  https://docs.brilo.ai/personal-assistants/playbooks.md
- To see calls: GET https://api.brilo.ai/v1/call
- To change how my owner's calls are answered (greeting, instructions, contact fields):
  https://docs.brilo.ai/personal-assistants/change-your-agent.md
- If my owner wants to cancel: POST https://api.brilo.ai/v1/agent/offboarding and give them the link
  it returns. I never cancel anything myself. How: https://docs.brilo.ai/personal-assistants/cancel.md
- If I have no key, set up again from that page.

Then tell your owner: “Saved. In any chat, just ask me to call someone.”

6. Make the first call

Send your key as Authorization: Bearer <api_key>. Ask your owner which number to call for the test, then ring them. Your owner’s agent is set up to answer their calls. Its saved greeting (“Hi, this is …‘s AI assistant. Who am I speaking with?”) is for people calling in, so every call you place brings its own script in agent_overrides:

Field	Required	What to send
`instruction`	Yes	What the call is for. Fill in the short template below.
`greeting`	Yes	The first thing the agent says when someone picks up. Calling someone your owner knows: “Hi Maya, this is Sam’s assistant, calling with a quick update.” Calling a business: say what the call is about, with no name: “Hi, I’m calling to book a table for two tonight.” See Calling a business.
`voicemail_behavior`	Yes, always send it	`LEAVE_MESSAGE` or `HANG_UP` if the call reaches voicemail. Send `LEAVE_MESSAGE` unless your owner says not to, so a call that reaches voicemail still gets the message through. The API does not check this one. Left out, it is `HANG_UP` unless you send a `voicemail_message`.
`voicemail_message`	Only with `LEAVE_MESSAGE`	The message to leave, word for word.
`summary_instruction`	Yes, always send it	What the call summary should tell you, so you can report back to your owner. The API does not check this one, but without it you get a generic summary.

Ready-made agent_overrides for common calls (a business, a phone menu, a hold queue, a voicemail) are in Playbooks. Fill in instruction yourself from what your owner asked for. Do not ask them for these; a line or two each is enough:

# Personality
Sam's personal assistant. Warm, brief and polite.

# Goal
Tell Maya that Sam's new assistant number is working.

# Guardrails
- Say you are Sam's assistant if asked. Never claim to be Sam or agree to anything on Sam's behalf.
- If Maya asks something not covered here, say you will check with Sam.
- Keep it under one minute.

The instruction replaces everything the agent knows, so put in it what the person answering will ask about:

Who the call is for: your owner or their business, by name, so the agent can answer “who is this?”. When calling a business, the agent gives this name only when asked.
The facts: who, what, where and when, and how to reach your owner. The agent has nothing else to go on.
What to do when it does not know: offer to check and follow up, or take a message. Never guess.

Write summary_instruction the same way, from what your owner will want to know: whether the person was reached, what they said, and anything they asked for, including whether and when they want a call back. Brilo does not schedule callbacks for you: remember the time and place that call yourself. The same call as a request body. In JSON the line breaks are written as \n:

{
  "agent_id": "...",
  "to": "+14155550123",
  "agent_overrides": {
    "instruction": "# Personality\nSam's personal assistant. Warm, brief and polite.\n\n# Goal\nTell Maya that Sam's new assistant number is working.\n\n# Guardrails\n- Say you are Sam's assistant if asked. Never claim to be Sam or agree to anything on Sam's behalf.\n- If Maya asks something not covered here, say you will check with Sam.\n- Keep it under one minute.",
    "greeting": "Hi Maya, this is Sam's assistant, calling with a quick update.",
    "voicemail_behavior": "LEAVE_MESSAGE",
    "voicemail_message": "Hi Maya, this is Sam's assistant. Just letting you know the new number works. No need to call back.",
    "summary_instruction": "Say whether Maya picked up and heard the message. List any question she asked or anything she wants Sam to do, in her words. Note if it went to voicemail or was a wrong number."
  }
}

Save it as call.json and send it:

curl -X POST https://api.brilo.ai/v1/call \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data @call.json

A call without an instruction or a greeting is refused with call_script_incomplete, and the response names what is missing. Calls ring straight away; they are not held for quiet hours. You can call and text numbers in the US and Canada.

Calling a business

When you call a business (a clinic, restaurant, shop or office), do not say your owner’s name in the greeting. Start with what the call is about. Give the name only when they ask, or when the task needs it, like booking under a name. The person picking up does not know your owner, and the name means nothing to them until then. If they ask for a number to reach your owner, give your Brilo number (phone_number from step 4), never your owner’s own phone. greeting:

Hi, I'm calling to book a teeth cleaning appointment.

instruction:

# Personality
A personal assistant calling on behalf of a client. Warm, brief and polite.

# Goal
Book a teeth cleaning at Bright Smile Dental for Sam Patel, any weekday morning in the next two weeks.

# Facts
- Name for the booking: Sam Patel. Sam is an existing patient.
- If they ask for a contact number, give the number you are calling from: +1 415 555 0199.

# Guardrails
- Do not give Sam's name until they ask who the appointment is for, or need it to look up or book.
- If asked who you are, say you are Sam's assistant, calling to book for Sam.
- Share only the facts above, and only when they are needed. Never give out anything else about Sam.
- Never agree to costs, cancellation fees or anything beyond the booking. Say you will check with Sam.
- If no morning slot works, take the two closest options and say Sam will call back to confirm.
- Keep it under three minutes.

voicemail_behavior: LEAVE_MESSAGE. voicemail_message: say what the call is about and leave your Brilo number, so they can call back and act on it. Leave out personal details: no name, date of birth, address, account or insurance numbers. Those wait until someone calls back and asks.

Hi, I'm calling to book a teeth cleaning appointment for an existing patient, any weekday morning in the next two weeks. Please call back on +1 415 555 0199 to set it up. Thank you.

summary_instruction:

Say whether an appointment was booked. If yes, give the date, time and any instructions they gave. If not, list the options they offered, in their words. Note if it went to voicemail, and if they asked for anything Sam needs to send or bring.

When they call back, your owner’s agent answers. It does not know about this call, so it takes a message for your owner. Tell your owner a callback may come in on their Brilo number.

When they may ask for something only your owner knows

Some calls will ask your owner’s details: a date of birth, an account number, a PIN. If the call you are placing might do that, turn on Ask a Human with ask_a_human inside agent_overrides. When the other side asks something the agent does not know, it puts them on hold, rings your owner, gets the answer, and carries on. Without it, the agent can only say it will check with your owner. Set when to the things they might ask for, in plain words. Do not send phone_number or human_label: the agent always rings your owner’s verified phone and uses their first name. Sending either is refused with ask_a_human_number_locked.

"ask_a_human": {
  "enabled": true,
  "when": "They ask for my owner's date of birth, an account PIN, or want to speak to the account holder"
}

Tell your owner before the call that their phone may ring, so they know to pick up. Your owner’s answers are in the call transcript. The call result lists each question and how it ended in ask_a_human, never the answer. Full details are in Ask a Human.

7. Find out how the call went

A call takes as long as it takes. Check GET /v1/call/{id}, waiting retry_after seconds between checks, and stop when retry_after is no longer in the response. Checking faster does not finish the call sooner.

`status`	Meaning
`queued`, `dialing`	Starting. Keep checking.
`in-progress`	Someone answered and the call is live.
`completed`	Over. Read `summary` (written to your `summary_instruction`) and `transcript`, and tell your owner what happened.
`failed`, `blocked`, `skipped`	It did not happen. Read the response before trying again.

If it went to voicemail

Voicemail is an answer, not a failure. Do not call again straight away: calling a business over and over looks like spam.

You left a message: you are done. They have your Brilo number and will call back. Tell your owner, e.g. “I left a voicemail at Bright Smile Dental asking them to call back on your Brilo number.” Do not call that number again for this task unless your owner asks.
You did not leave a message: you may try once more, at least 2 hours later and during their business hours. Leave a message that time.
At most 2 calls to the same number for the same task. After that, stop and tell your owner.

Errors

Errors carry code, message and action. Limit errors also carry limit, used and resets_at, so you can tell your owner exactly when they can try again.

`code`	HTTP	Where	What to tell your owner
`slow_down`	429	`/poll`	Nothing. Wait `retry_after` seconds.
`rate_limited`	429	any	Nothing. Wait `retry_after` seconds.
`pairing_not_found`	401	`/poll`	Start a new pairing and show them the new code.
`pairing_key_replaced`	201 (a normal reply)	`/poll`	This pairing’s key is no longer active. Start again only if they ask you to.
`hourly_call_cap`	429	`/call`	20 calls an hour is the limit. Tell them when it resets.
`daily_call_cap`	429	`/call`	100 calls a day is the limit. Tell them when it resets.
`daily_minute_cap`	429	`/call`	600 call minutes a day is the limit. Tell them when it resets.
`destination_call_limit`	429	`/call`	That number has had 10 calls today, or 30 this month. Do not retry it.
`destination_not_supported`	400	`/call`, texts	Only numbers in the US and Canada can be called or texted.
`call_script_incomplete`	400	`/call`	Nothing. Add the fields listed in `missing` and send the call again.
`ask_a_human_number_locked`	400	`/call`	Nothing. Remove `phone_number` and `human_label` from `ask_a_human` and send the call again.
`owner_phone_missing`	400	`/call`	Your owner needs to add and verify a phone number on their Brilo account. Then send the call again.
`owner_phone_lookup_failed`	503	`/call`	Nothing. Send the call again in a few seconds.

Check what is left before you call: GET /v1/usage returns each limit with limit, used, remaining and resets_at. Full request and response shapes are in the API reference.

Keep it safe

Your owner can disconnect you at any time, and can replace your key by connecting you again from a newer install. Other assistants on the same number keep working either way.
If your owner asks to cancel, follow When your owner wants to cancel. Never try to cancel yourself.
One call at a time: while a call is live, a second one is refused.
For machine-readable docs, read /llms.txt, or add .md to any page URL.

Start here

Personal assistants

Configure

Test

Deploy

Common jobs

Campaigns

Monitor

Fix a problem

Accounts and workspaces

Good to know

Setup steps for your assistant

Rules

1. Start

2. Show your owner the link and the code

3. Check until it is done

4. Save your key

5. Remember that you can make calls

6. Make the first call

Calling a business

When they may ask for something only your owner knows

7. Find out how the call went

If it went to voicemail

Errors

Keep it safe

​Rules

​1. Start

​2. Show your owner the link and the code

​3. Check until it is done

​4. Save your key

​5. Remember that you can make calls

​6. Make the first call

​Calling a business

​When they may ask for something only your owner knows

​7. Find out how the call went

​If it went to voicemail

​Errors

​Keep it safe

Rules

1. Start

2. Show your owner the link and the code

3. Check until it is done

4. Save your key

5. Remember that you can make calls

6. Make the first call

Calling a business

When they may ask for something only your owner knows

7. Find out how the call went

If it went to voicemail

Errors

Keep it safe