Write a Chat Agent's Prompt

The prompt is where a chat agent learns its job — how to greet a customer, what to ask, which details to capture, and when to hand off to a human. Get it right and the agent reads like a short playbook a trained sales or support rep could follow over WhatsApp; get it wrong and replies run long, skip questions, or guess. This page shows you how to write that playbook with chat-friendly rules and live variables.

Entry pointAutomation → AI Assistants → Agents → [agent] → Build → Prompt

Article summary	Details
Requires	Permission to edit the agent.
Where to go	Automation → AI Assistants → Agents → [agent name] → Build → Prompt.

---

Open the Prompt Tab

1. Open Automation → AI Assistants → Agents and select the chat agent you want to edit.
2. Make sure you're on the Build tab.
3. In the left sidebar, select Prompt.

The Prompt editor opens on the right. A list of All Variables appears on the far right.

---

Write or Update the Prompt

The editor has two modes:

• View — formatted preview. Use it to read the prompt as the agent will see it.
• Edit — Markdown editor. Use it to write or change the prompt.

1. Select Edit in the top-right of the editor.
2. Write the prompt in Markdown. The toolbar covers bold, italic, H2, bulleted lists, numbered lists, and a horizontal divider.
3. Insert a variable by clicking it in the right-hand All Variables panel — it inserts at the cursor as {{variable_name}}.
4. Switch back to View to preview, or expand to full screen with the arrows icon at the top-right of the editor.
5. Select Save in the agent header to persist the change.

Markdown is supported, including headings, lists, and bold/italic. Keep the prompt scannable — short paragraphs and bulleted rules behave better than long blocks of prose, especially on chat where the LLM tries to mirror your tone.

---

Use Variables

The right-hand All Variables panel lists every value you can drop into the prompt. They're grouped into three blocks.

Group	Variables	When the value is set
System Variables	agent_name, callee_name, business_name	Pre-filled automatically per conversation from the agent record and the contact.
Pre-Chat Variables	Custom — you define them.	Passed in when the conversation is started (from a campaign, a workflow trigger, or an API call).
Action Results	Returned by tools the agent runs.	Filled mid-conversation by tool outputs — useful for downstream tool steps or post-chat analysis.

Reference a variable in the prompt with double curly braces, for example Hi {{callee_name}}, I'm {{agent_name}} from {{business_name}}.

---

Add a Pre-Chat Variable

Use pre-chat variables when you need the same agent to handle different campaigns, sources, or customer segments without writing a new prompt.

1. In the All Variables panel, select + Add.
2. Enter the variable name, type, and an optional default value.
3. Save the variable. It appears under Pre-Chat Variables.
4. Reference it in the prompt with {{variable_name}}.
5. Pass the value in when the conversation starts — from a campaign config, a workflow step, or an API call.

Use pre-chat variables for the few details that genuinely change conversation to conversation (source campaign, offer name, follow-up reason). Put fixed business facts in the prompt or a knowledge base.

---

Prompt Structure That Works

A working chat prompt usually has four sections.

1. Role and goal

State who the agent is, who it represents, and what counts as success.

You are {{agent_name}}, a chat assistant for {{business_name}} replying to leads who messaged us about residential properties. Your job is to confirm interest, capture qualification details, and book a follow-up when the customer is ready.

2. Conversation rules

Direct rules. Chat is short-form and the agent should not need to infer critical behaviour.

• Greet the customer by name when available.
• Ask one question at a time.
• Keep answers under three lines unless the customer asks for more detail.
• Use the attached knowledge base for facts. Do not invent prices, inventory, legal terms, payment, or policy details.
• Hand off to a human via the user_handoff tool when the customer asks for one or signals strong intent.
• End politely when the customer is not interested, says they are the wrong person, or asks not to be contacted.

3. Required qualification questions

List the exact fields to capture before the conversation counts as qualified.

Ask	Why it matters
What are you looking for?	Product or project fit.
Where (city, locality)?	Routing to the right team.
Approximate budget?	Lead quality.
Timeline to buy / decide?	Priority.
Preferred next step — site visit or callback?	Next action.

4. Handoff and stop conditions

When to hand off:

• The customer asks for a person.
• The customer is angry, confused, or raises a complaint.
• The customer asks for negotiation, custom pricing, or a legal commitment.
• The agent cannot answer after checking knowledge.
• The customer gives a strong intent signal (I want to book today).

When to stop:

• The number / handle belongs to the wrong person.
• The customer asks not to be contacted.
• The customer says they are not interested.
• The customer asks for a later callback.
• The conversation hits the Maximum number of messages limit.

---

Chat-Specific Rules

Chat behaves differently from voice. Add these to every chat prompt:

• Length cap. Voice calls allow long answers; chat shouldn't. Add "Keep replies under three short lines unless asked for more."
• No filler. Voice agents can say "Just one moment …"; chat shouldn't. Replies should commit to an answer or the next question.
• Emoji policy. Decide once and put it in the prompt — "Use one emoji per message at most." or "No emojis."
• Media handling. If the customer sends an image or a document, acknowledge it explicitly: "Got the photo — I'll pass it on to our team."
• Repeat-customer aware. Chat conversations can pause for days. Tell the agent how to re-open one: "If the last message is older than 24 hours, restate who you are before continuing."

Don't let the agent send more than one message in a row without waiting for a reply. Add a rule: "Wait for the customer's next message before sending anything else."

---

Prompt Quality Checklist

• The first lines explain who the agent is and why it's messaging.
• The agent asks one question at a time.
• The agent has a length cap (under three short lines unless asked).
• The agent knows which fields or outcomes to capture.
• The agent has explicit handoff and stop rules.
• The agent has a rule against guessing prices, inventory, or policy.
• The agent knows which topics belong to the knowledge base.
• The agent has a polite closing line for every outcome.
• The agent waits for a reply before sending more.

---

Troubleshooting Prompt Issues

Problem	What to change
Agent's replies are too long	Add a rule to answer in two or three short sentences unless the customer asks for detail.
Agent sends two messages back-to-back	Add an explicit rule: "Wait for the customer's next message before sending anything else."
Agent skips qualification questions	List the required questions in the exact order they should be asked.
Agent gives unapproved answers	Add restricted topics and attach a reviewed knowledge base.
Agent does not hand off soon enough	Add clearer handoff triggers and attach the User Handoff or Route To tool.
Agent ends without an outcome	Add explicit outcome labels and use post-chat analysis to capture them.
Variable shows as {{...}} on the live conversation	Confirm the variable is in All Variables, the name matches exactly, and pre-chat variables are passed in when the conversation starts.
Agent uses emojis when it shouldn't	Add an explicit emoji rule to the prompt. The model defaults to using them in chat.

---

If the Prompt editor won't let you into Edit mode, you don't have edit rights on this agent — that's one for your admin. Behavior problems, on the other hand, are almost never access problems: long replies, skipped questions, and rogue emojis are prompt issues, and the troubleshooting table above is the faster fix.

Contact Brixi support if a saved prompt isn't being applied to new conversations, or a pre-chat variable that's defined and passed in correctly still shows as {{...}} in live messages. Include the agent ID, the variable name, and a transcript that shows it.

Related articlesAI Chat Agents (overview)Create and Configure a Chat AgentKnowledge Base for Chat AgentsChat ToolsTest a Chat Agent Before LaunchPost-Chat Analysis