Writing instructions
On this page
The instructions box is where most of your agent’s quality comes from — and where almost every problem people blame on “the AI” actually lives. This page gives you a structure to copy and the handful of rules that matter on a phone call specifically.
Why this page matters more than the rest
Before every single reply, the agent re-reads its instructions in full and decides what to say next. That has three consequences worth internalising:
- Anything ambiguous will be resolved differently on different calls. If two lines can be read as conflicting, you will get both behaviours and it will look random.
- Length costs time. A very long prompt is re-read on every turn, and the caller hears that as hesitation. Reference material belongs in a Knowledge Base, not here.
- Unstated things get invented. Not out of malice — the model fills gaps. The fix is never “be more accurate”; it is telling it what to do when it does not know.
The structure to copy
Paste this into the instructions box and replace the braces. The headings are doing real work — they keep related rules together, which makes the agent apply them together.
## Who you are
You are {name}, the {role} for {business} in {location}.
## What this call is for
{One sentence. The single outcome that makes this call a success.}
## How to speak
- Keep replies to one or two sentences.
- Ask one question at a time, then wait.
- Warm and direct. No corporate filler, no repeating the caller back to themselves.
- If you are interrupted, stop and listen.
## What you know
- Hours: {…}
- Prices: {…}
- Address: {…}
- We do: {…}
- We do NOT: {…}
## What to do
1. {First thing — usually: find out why they are calling.}
2. {Second thing.}
3. {How the call should end.}
## Rules you never break
- Never invent a price, a date, or a policy. If you do not know it, say so.
- If the caller asks for a human, is upset, or you have failed twice, transfer the call.
- Never promise anything outside {business}'s control.
- {Your own regulated / legal line, if you have one.}
## When you are unsure
Say: "I don't want to give you the wrong information — let me have {someone}
call you back on this. What's the best number?" Then take the number and end
the call politely.Rules you never break and When you are unsure. Almost every “it made something up” report comes from an agent that had neither. Write them before you write the friendly bits.
Rules specific to a phone call
Instructions written for a chatbot fail on the phone. There is no screen, no scrolling back, and the caller cannot re-read anything.
| Do | Instead of | Because |
|---|---|---|
| “One or two sentences per reply.” | Letting it answer at length | A paragraph over the phone is unbearable, and the caller has forgotten the start by the end. |
| “Ask one question at a time.” | “Collect name, email and preferred date.” | Asked three at once, callers answer one and you lose the others. |
| “Never read out a code or long number. Offer to text it.” | Reading references aloud | Nobody has a pen. Use a Send Message tool instead. |
| “Confirm the day and time back before ending.” | Booking silently | It catches misheard details while the caller is still on the line. |
| “If they interrupt you, stop and listen.” | Nothing | Talking over a caller is the single most common complaint about voice agents. |
| “Spell out amounts as you would say them.” | Raw figures | “Three thousand five hundred shillings” beats an agent stumbling over KSh 3,500. |
Two worked examples
Inbound: a dental receptionist
Note how the tool names appear in the instructions. The agent has the calendar integration attached, and step 2 tells it when to reach for it — that pairing is what turns a talker into a booker.
## Who you are You are Amara, the receptionist for Brightsmile Dental in Westlands, Nairobi. ## What this call is for Book, move or cancel an appointment — or take a message if you cannot. ## How to speak - One or two sentences per reply. Ask one question at a time. - Friendly and efficient. This is a busy front desk, not a call centre. ## What you know - Open Mon–Fri 8am–6pm, Sat 9am–1pm. Closed Sunday. - Cleaning KSh 3,500. Consultation KSh 2,000. Whitening from KSh 15,000. - We are on the 3rd floor of Delta Towers. Free parking in the basement. - We do NOT do orthodontics — we refer those to Dr Kimani. ## What to do 1. Greet, then ask if they are booking, changing, or asking a question. 2. If booking: use check_availability before offering any time. Never offer a slot you have not checked. 3. Collect full name and phone number, then use create_event to book it. 4. Read the confirmed day and time back to them before ending the call. ## Rules you never break - Never quote a price that is not in the list above. - Never give clinical or medical advice. Say a dentist will advise at the visit. - If they ask for orthodontics, refer to Dr Kimani and offer to text the number. - If the caller is distressed or in pain, transfer to the clinic immediately.
Outbound: a collections call
Outbound to someone who did not ask to be called is the highest-risk thing you can do with this platform, so the rules section is longer than everything else combined. That ratio is correct.
## Who you are
You are calling on behalf of Sunrise Credit about an overdue account.
## What this call is for
Confirm you are speaking to the right person, then agree a payment date.
## How to speak
- Calm, respectful, never pressuring. This person may be having a hard month.
- Short sentences. Let silences sit — do not fill them.
## What to do
1. Ask for {{customer_name}} by name. If it is not them, apologise and end the
call. Do not discuss the account with anyone else.
2. Say who you are, that the call is recorded, and why you are calling.
3. Ask when they expect to be able to pay.
4. Confirm the date back to them and thank them.
## Rules you never break
- Never discuss the balance, the account, or the debt with anyone other than
{{customer_name}}. Not a spouse, not a colleague.
- Never threaten legal action, fees, or consequences of any kind.
- If they dispute the debt, say it will be reviewed and transfer the call.
- If they ask you to stop calling, confirm you will and end the call.
- Never continue if they say this is a bad time. Offer to call back.Calling windows, consent, do-not-call handling and recording disclosure are not optional in most markets, and the platform enforces some of them for you. Read Consent & calling rules before you run an outbound agent at any volume.
Fixing a misbehaving agent
Open the transcript in Call History, find the exact turn that went wrong, and match it to a row below. Do not rewrite the whole prompt — change one thing and call again.
| Symptom in the transcript | The actual cause | The fix |
|---|---|---|
| Invented a price or a policy | The fact was missing and there was no “say you don’t know” rule | Add the fact, and add the “When you are unsure” block. |
| Ignores one of your rules | It contradicts another rule elsewhere in the prompt | Search for the conflict. Two “always” rules that cannot both hold produce coin flips. |
| Long, rambling replies | No length rule | Add “One or two sentences per reply.” near the top, not buried at the bottom. |
| Asks a question it already has the answer to | The answer arrived in a way it was not told to expect | Add “The caller’s name and number are already known — do not ask for them again.” |
| Never uses a tool it has | Nothing tells it when to | Name the tool in the steps: “use check_availability before offering a time.” |
| Refuses things it should do | An over-broad restriction | Narrow it. “Never give medical advice” is right; “never discuss health” blocks the whole call. |
| Drifts off-topic when the caller does | No boundary | Add “If the conversation moves away from {topic}, politely bring it back.” |
Rewriting five things and re-testing tells you nothing about which one worked. One change, one test call, one transcript. It is slower per round and much faster overall.
Variables
These are replaced with real values as the call begins, so the same instructions work for every caller.
| Variable | Becomes |
|---|---|
{{company_name}} | Your business name as set on the account |
{{phone_number}} | The number involved in this call |
{{agent_name}} | This agent’s name |
{{date}} | Today’s date |
{{time}} | The current time |
Put Today is {{date}}. near the top of any agent that deals with appointments. Without it the agent has no reliable idea what “tomorrow” or “next Tuesday” means, and it will guess.
Campaigns and lead callbacks can carry extra fields from your contact list or lead form — a customer name, an amount, a policy number — which you reference the same way. See Campaigns and Lead Callback.
Instruction questions
How long should instructions be?
Most good agents land between 200 and 600 words. Under 100 and you are relying on the model’s assumptions. Over about 1,000 and you are paying for it in response time, and it is a sign that reference material has crept in — move that to a Knowledge Base.
Should I write in English if the agent speaks another language?
Write the instructions in English and set the language separately. The agent will speak the configured language. Exception: exact phrases you want said verbatim — a legal disclosure, a brand line — should be written in the target language, in quotes.
Can I use markdown headings and lists like the examples?
Yes, and you should. Structure helps the model group related rules. Just remember it is never read aloud — it shapes behaviour, not speech.
What is the difference between the greeting and the instructions?
The greeting is the exact first sentence, said before the caller has spoken. The instructions govern everything after. Keep the greeting short and identify yourself in it — that is also where a required AI disclosure goes.