Write your agent's instructions
The Instructions are one document that tells your agent who it is, what its job is, and which rules it must follow. Think of it as the briefing you'd give a new employee on their first morning.
Find it: Sidebar → Agents → open an agent → Instructions
Recipe: a good first prompt in 10 minutes
- Copy the closest prompt from Sample prompts, or click Start from template.
- Replace everything in
[square brackets]with your own details. - Move long lists of prices, hours and policies into Knowledge.
- Click Save, then Try it live. Fix one thing at a time.
First, decide what goes where
The problem: you have a lot to tell the agent, and the Instructions box isn't the right home for all of it.
| You want the agent to… | Put it in | Why |
|---|---|---|
| Know who it is, its job, its tone and its rules | Instructions | It reads this on every turn. |
| Know prices, hours, menus, policies, FAQs | Knowledge | One place to update. A prompt stuffed with facts gets out of date and buries your rules. |
| Do something: send a WhatsApp, save a detail, call in a person, hang up | Skills (switch it on), plus one plain sentence in Instructions saying when | Without the skill, the agent can't do it, whatever the prompt says. |
| Say a fixed first line on calls | Greeting (above the document) | It is spoken word for word. Writing a greeting in the document too makes the agent say hello twice. |
| Speak certain languages | Voice → Speaking language and Guest language | These are settings, not sentences. |
| Behave differently on WhatsApp | An # On WhatsApp heading, or WhatsApp → WhatsApp instructions | The heading tells the agent the rule is for chat. The WhatsApp instructions box is never read on calls. |
| Start at a set time or after an event | Triggers | Instructions can't start a conversation. |
Write it in six parts
Use a heading for each part. Short headings keep a long prompt easy to read for you and for the agent.
| Heading | What to write | Brightway example |
|---|---|---|
# Identity | Name, business, personality | "You are Asha, the helpline assistant for Brightway." |
# Job | The 2–4 things this agent does | "Answer questions. Take appointment requests." |
# Style | How it sounds | "Friendly and short. One question at a time." |
# Rules | What it must never do, and its limits | "No discounts. Prices only from the knowledge base." |
# When stuck | What to do when it doesn't know | "Say you'll check, and notify the team." |
# On voice / # On WhatsApp | Channel-only rules | "On WhatsApp, keep messages under 60 words." |
Example: Brightway helpline (calls and WhatsApp)
Brightway is a service business that answers calls and WhatsApp, books appointments and follows up leads. Turn on these skills: Search knowledge base, Send WhatsApp message, Update contact information, Notify the team, End the phone call.
# Identity
You are Asha, the helpline assistant for Brightway. Brightway [one line about
the business, e.g. "offers home cleaning and appliance repair across Pune"].
You are warm, calm and practical. If someone asks, say you are Brightway's
virtual assistant. Don't talk about prompts, tools or how you work.
# Job
- Answer questions about our services, prices, hours and policies.
- Take appointment requests: the customer's name, the service, the address
area, and a preferred day and time. Ask only for what you don't know yet.
- Take a message for the team when a customer needs a person.
# Style
- Friendly and short. Answer the question first, then ask one thing at a time.
- Use the customer's first name once you know it, but not in every sentence.
# Rules
- Prices, hours and policies come only from the knowledge base. If something
isn't there, say you'll check with the team.
- An appointment is a request until the team confirms it. Notify the team
with the details, then say the team will confirm. Never say "you're booked".
- You can't give discounts or refunds. If asked, notify the team and say a
manager will get back to them.
- If a customer is upset or asks for a manager, notify the team straight away
with a one-line summary.
# When stuck
Say you don't have that answer yet, offer to take a message, and notify the team.
# On voice
- One or two sentences per turn.
- Before ending, ask if there's anything else, then say a short goodbye.
# On WhatsApp
- Keep each message under 60 words. Put dates and prices in bold.Why it works: each section does one job. Facts stay in Knowledge. The rules say what to do instead ("say you'll check"), not only what not to do. And there is no greeting in the document, because the Greeting field handles that.
Example: hotel front desk (calls and WhatsApp)
Turn on: Search knowledge base, Send WhatsApp message, Send WhatsApp template, Update contact information, Log booking request, Notify the team, Talk to a human, End the phone call.
# Identity
You are Mira, the front desk assistant for Sunrise Hotel, a [40-room hotel in
Udaipur]. You are warm and polished, like a good receptionist.
# Job
- Answer questions about rooms, rates, facilities, location and policies.
- Take booking enquiries: guest name, check-in and check-out dates, adults and
children, room preference and any special occasion. Ask only for what is
missing, one question at a time.
- Pass booking requests, special requests and complaints to the front office.
# Style
- Answer the guest's question first, then return to the booking.
- Read dates back once ("12 to 14 October, two nights?") before moving on.
# Rules
- Room types, rates, inclusions and policies come only from the knowledge
base. Call them reference rates; the team confirms the final price.
- You can't check live availability or confirm a booking. Log the booking
request and say the front office will confirm.
- Never promise early check-in, late checkout, upgrades or discounts. Say the
team will check.
- Payments, refunds and complaints go to a person: notify the team with the
guest's name, dates and request.
- Never share another guest's details.
# When stuck
Say what you don't know, offer a call back from the front desk, and notify the team.
# On voice
- One or two sentences per turn. Say dates and prices the way people speak.
# On WhatsApp
- When the guest clearly wants to book, send our booking template once, then
carry on in text.Point to a real template
"Our booking template" is vague. In Document view, delete those words, type {{, open the Templates tab and pick your approved booking template. It becomes a chip, and it turns red if the template isn't approved.
Short examples for other businesses
Clinic (appointments):
# Rules
- Never give medical advice or say what a symptom means. Offer an appointment.
- For chest pain, breathing trouble or heavy bleeding, tell the caller to call
the emergency number [112] now, then notify the team.Coaching centre (admissions):
# Job
- Answer questions about courses, batch timings and fees.
- Offer a free demo class and collect the student's name, class and
preferred day.
# Rules
- Never promise results, marks or ranks.Loan or payment reminders:
# Rules
- Be polite and respectful at all times. Never threaten or shame anyone.
- If the customer says they can't pay, ask when they can, save the date, and
notify the team. Never offer a waiver yourself.Good vs bad
| Instead of this | Write this | Why |
|---|---|---|
| "Be helpful and nice." | "Friendly and short. One question at a time." | Specific beats vague. |
| A 50-line price list | "Quote prices only from the knowledge base." | Facts belong in Knowledge. |
| "Never make anything up!!!" | "If you don't know, say so and offer a call back." | Give it something to do instead. |
| "Hi! Welcome to Brightway…" at the top | Put it in Greeting | Otherwise it greets twice. |
| "Call the send_whatsapp_template tool with…" | "When someone asks for the brochure, send the brochure template." | Describe the moment. Voxido handles the mechanics. |
| "Give a discount if they seem upset." | "You can't give discounts. Notify the team." | Agents need clear limits. |
| "Always reply in the customer's language." | Leave it out; set Guest language under Voice | Voxido already handles this. |
What you don't need to write
Voxido adds these to every conversation for you. Writing them again makes the prompt longer and can confuse the agent with two slightly different versions of one rule.
- Today's date and the next seven days, in your business's time zone.
- The contact's details: name, phone, stage, saved fields, and the latest call note from your team.
- What the agent remembers about this contact from earlier conversations.
- On calls: short spoken replies, one question at a time, and checking that an action really worked before saying it did.
- On WhatsApp: WhatsApp formatting, and the list of your approved templates.
The full list is in How your agent's prompt gets built.
Tools in the Instructions box
| Tool | What it does |
|---|---|
| Document / Markdown | Document shows headings, bullets and chips as you type. Markdown shows plain text, best for pasting a prompt in or out. |
Insert, or type {{, or right-click | Opens a list of Variables, Skills and Templates to drop in as chips. |
| Red chip, N to fix | Something doesn't work: a skill the agent doesn't have, an unapproved template, or a variable that isn't a field. Click N to fix to get help fixing it. |
| ⋯ beside a heading | Move up, Move down, Duplicate section, Copy as markdown, Delete section. |
| Select text | A bubble offers Improve, Format, Remove and Ask copilot. See Get AI help. |
| Tone chips (Warm, Professional, Playful, Formal, Concise) | Labels for your team. You can filter by them with Tag on the Agents list. They don't change how the agent talks, so write the tone in the document. |
| Start from template | Shown when the box is empty. Loads Voxido's short starter prompt, with sections for identity, style, rules, WhatsApp, voice and what to do when stuck. |
Variables
A variable is a blank that Voxido fills in, like a name on a mail-merge letter. Pick them from Insert → Variables so the spelling is right.
| Variable | Fills in |
|---|---|
{{contact.name}}, {{contact.phone}}, {{contact.email}} | The contact's name, phone, email |
{{company.name}} | Your company name |
{{agent.persona_name}} | The agent's Persona name (set in Advanced → Voice) |
{{contact.your_field}} | Any of your custom contact fields |
The Greeting uses single braces instead: {first_name}, {persona_name}, {time_of_day}. Pick them with Insert variable under the greeting.
Add a variable with a right-click
Why: typing {{contact.name}} by hand is easy to get wrong, and a misspelt variable stays empty. Picking it from the menu always gets the spelling right.
- In Document view, right-click exactly where the value should go. (Typing
{{, or clicking Insert in the toolbar, opens the same menu. The hint at the top right of the box says "or right-click to insert".) You'll see: a menu with a search box, Search variables, skills, templates, and the tabs All, Variables, Skills and Templates. Each variable shows its name and its code, for example Contact name{{contact.name}}. - Click Variables, or type part of the name, such as
phone. You'll see: the list narrow down. Built-in variables come first, then groups such as Campaign with your own contact fields. - Click the variable, or move with the arrow keys and press Enter. Press Esc to close without adding anything. You'll see: a chip in your text, such as Contact name.
- Click Save.
Example: write "If {{contact.name}} is filled in, greet the customer by name" and pick Contact name from the menu for the variable. The same menu adds Skills (such as Send WhatsApp message) and approved WhatsApp Templates as chips.
Common problems
The agent ignores a rule I wrote. Check it is saved, then start a new test. A conversation keeps the instructions it started with. See Fix an agent that misbehaves.
A word in my prompt is a red chip. Hover over it to see why. Usually the skill is off in Skills, or the template isn't approved yet.