Write your bot's instructions

Your bot's instructions (the Prompt in its settings) tell it who it is, who it's helping, what it may talk about, how to answer and what to do when it can't help. Chat Thing sends the prompt with every message, so it shapes every reply. This page walks through each part with short before-and-after examples. For complete prompts you can copy and adapt, see the prompt library.

Who can do this: team owners and admins.

Edit the prompt

1. Open your bot and go to the General settings tab.
2. Find the Prompt field.
3. Write your instructions, or start from a draft:
   • Adapt our prompt (under the field) fills it with the default prompt so you can edit it.
   • Generate with AI (above the field) writes a prompt from a short description of what the bot should do. It replaces the existing prompt, so copy anything you want to keep first.
4. Click Update bot. The next message anyone sends uses the new prompt.

If you leave the prompt blank, the bot uses this default:

You are a helpful assistant.
- Use information from the provided context below in markdown format to help answer questions.
- If the answer is not clear from the context or your internal knowledge make this clear.
- Include any relevant media or code snippets.

The default works for a quick test, but it doesn't say who the bot works for, what's off limits or when to hand over, so write your own before you launch.

You can also change the prompt by asking Otto ("Make the tone more formal") or from an AI assistant through the Chat Thing MCP server, which reads and writes the same Prompt field.

What the bot sees with every message

Knowing what arrives alongside your prompt helps you write instructions that fit. For each reply, the bot receives:

• Your prompt.
• Relevant knowledge: the passages from your data sources that best match the question. You don't need to paste your content into the prompt.
• The conversation so far, up to Max message history (12 messages by default). Your Welcome message is saved as the bot's first message, so the bot sees it too.
• Today's date, in the visitor's time zone when the widget reports one.
• Visitor details, when you have them: answers to your pre-chat form, details sent with identifyUser, or the name and number of a WhatsApp contact.
• Each power-up's name and Description, for every power-up that's turned on.

The Bot description is only shown on your bot's landing page and is never sent to the bot, so put instructions in Prompt, not there.

The prompt, the knowledge and the conversation share one token budget, set by Max context size in model settings. There's no fixed character limit on the prompt, but a very long one leaves less room for knowledge and uses more message tokens on every reply. Most good prompts fit in 150 to 400 words. For how these pieces combine into an answer, see How your bot answers.

A structure that works

Write the prompt as short sections with plain headings or bullet points. The model follows clear, separate rules better than one long paragraph. Put the rules that matter most (scope, what to do when it doesn't know, safety) near the top.

Role: who you are, who you work for, who you're talking to.
Scope: what you help with, and what to do with anything else.
Answering: where answers come from, length, format, language.
Tools: when to use each power-up.
Handoff: when and how to pass the conversation to a person.
Never: things you must not do.

The sections below cover each part.

Tell the bot who it is and who it's helping

Describe how the bot should behave and who it's talking to, not a backstory. "You have 10 years of experience" doesn't change how it writes; "our customers aren't technical, so avoid jargon" does.

Before

You are an expert assistant.

After

You are the support assistant for Acme, which makes accounting software
for small businesses. You talk to business owners and their staff, who are
usually not accountants. Explain things in plain language.

Keep the bot on topic

Without a scope, the bot will happily write poems, answer homework or discuss your competitors. Say what's in scope and give it a polite way to decline.

Before

Answer any question the user asks.

After

Only help with Acme's products, pricing, accounts and billing.
If someone asks about anything else, say politely that you can only help
with Acme, and ask if there's anything about Acme you can help with.
Don't write code, essays or content unrelated to Acme, even if asked.

A friendly refusal keeps the conversation going. Avoid wording that sounds like an error, such as "I am unable to process that request."

Answer only from your knowledge

Decide whether the bot may use its general knowledge or only your content. For support, pricing and policy questions, restrict it: a confident guess about a refund window is worse than no answer.

Before

Use the context to help answer questions.

After

Answer only from the information provided to you. If it doesn't cover
the question, say you don't have that information. Never guess prices,
dates, policies or product features.

If you want the bot to fill gaps with general knowledge (for example, a cooking site answering "how long do I rest a steak?"), say where the line is: "You may use general knowledge for cooking questions, but prices, stock and delivery must come only from the information provided."

Lowering Creativity (temperature) also makes the bot stick more closely to your content and prompt.

Say "I don't know" and hand over to a person

Every bot meets questions it can't answer. Tell it what to do instead of guessing, and give it a way out.

Before

If you don't know, say so.

After

If you can't answer from the information provided, say so in one sentence
and offer to pass the conversation to the team.
Offer the handoff straight away if the user asks for a person, is upset,
or the issue involves a payment, a complaint or a damaged order.
Use Talk to a human to hand over. Don't offer a handoff more than once
unless the user asks again.

For the bot to actually hand over, add the Talk to a human power-up (paid plans). It asks for the visitor's email and emails your team the conversation. On Standard and above, turn on human takeover too, so your team can reply live in the widget.

Set the tone and brand voice

Show the tone with a short example exchange rather than a list of adjectives. The bot copies examples closely, so keep them short and typical.

Before

Be friendly and professional.

After

Write like a helpful person on our team: warm, direct and plain.
Use "you" and "we". No exclamation marks, no emojis.

Example:
User: Can I change my plan?
You: Yes. Go to Settings > Billing and choose Change plan. The new price
starts from your next bill.

Add explicit "don'ts" for habits you want to stop, such as "Don't apologise more than once" or "Don't say 'according to the context'".

Make answers shorter

Bots tend to write too much. Set a default length and say when longer answers are fine.

Before

Give detailed and comprehensive answers.

After

Keep answers to 2–3 sentences. Use a numbered list only for step-by-step
instructions. If the full answer is long, give the key point and offer
more detail.

Format answers for each channel

The same prompt is used on every channel your bot is connected to, but channels display text differently:

If one bot serves both the widget and WhatsApp, Telegram or email, keep formatting light for everyone:

Write in plain sentences. Use simple numbered lists if you need steps.
Don't use headings, tables, bold text or markdown links. Write web
addresses out in full, like https://example.com/returns.

For different formatting per channel, duplicate the bot and give each copy its own prompt and channel.

Control which language the bot answers in

Most models reply in the language the visitor writes in, but say so to be sure, and say what to do with the knowledge if it's in another language.

Always reply in the language the user writes in, even though the
information provided is in English. Keep product names in English.

To use one language whatever the visitor writes: "Always reply in German." The widget's Language setting only translates the widget's buttons and labels; it doesn't change the answer language. See Languages.

Tell the bot when to use power-ups

The bot decides whether to use a power-up from its Description and your prompt. Use the power-up's own settings for how it works, and the prompt for rules across the conversation: when to use it, in what order, and when not to.

Refer to a power-up by the Power-up name shown on its card, such as "Talk to a human" or "Book a meeting". Don't name a power-up the bot doesn't have: it can't use it, and may tell the visitor it has done something it hasn't.

Before

Help people book demos.

After

If someone wants a demo, a call or to talk to sales, offer a meeting and
use Book a meeting to show the available times. Don't offer a meeting to
people asking support questions about an existing account.
Never say a meeting is booked until Book a meeting confirms it.

See How power-ups work for writing descriptions.

Collect details from visitors

When the bot needs details (an order number, an email, a company name), tell it exactly what to ask for, when, and to ask one thing at a time.

Before checking an order, ask for the order number (it starts with AC-)
and the email address used for the order. Ask for one at a time.
If you already know the user's email from their details, don't ask again.
Once you have both, use Check order status.

To collect details before the chat starts, use a pre-chat form instead. The answers reach the bot with every message, so the prompt can refer to them.

Stop the bot making promises it can't keep

A bot can sound authoritative about things it shouldn't decide. Spell out what it must never do.

Never:
- Promise refunds, discounts, compensation or delivery dates. Explain the
  policy and offer to pass the request to the team.
- Give legal, medical, tax or financial advice. Suggest a professional.
- Ask for passwords, full card numbers or other sensitive details. If a user
  shares them, tell them not to and don't repeat them.
- Discuss or criticise competitors.

Anyone can chat with a public bot and try to talk it out of its rules. Rules like these reduce the risk but can't guarantee it, so don't connect a public bot to data or actions it shouldn't expose.

Personalise answers with visitor details

When the bot knows who it's talking to, it can greet people by name and skip questions. Visitor details come from:

• identifyUser on your website: id, name, email, tel and timeZone.
• Your pre-chat form: each answer is saved under a key made from its label, such as company_name.
• WhatsApp: the contact's name and phone number.
• The Chat API: userData sent when you start a conversation.

The bot receives these as user data with every message. Refer to them in plain words:

If you know the user's name, use their first name in your first reply.
If you know their email, use it for handoffs instead of asking for it.

To give the bot facts about the page or account, such as the visitor's plan or the product they're viewing, send page context from the SDK. It arrives with the knowledge for each message, so you can write rules like "If the user is on the Free plan, mention which features need an upgrade." Page context needs Advanced SDK features turned on.

identifyUser isn't verified, so never write rules that give some users access to information based on these details.

Check it works

1. Click Test in your bot's header, or chat with it on your site.
2. Ask the five questions your customers ask most, and check the answers, length and tone.
3. Ask something off-topic, something your knowledge doesn't cover, and ask for a person. Check the bot declines politely, admits it doesn't know and offers the handoff.
4. Try the same questions in another language and, if you use them, on WhatsApp or email.
5. Change one thing at a time and ask the same questions again.

To re-check answers automatically after every change, set up test cases (Enterprise plan). You can also ask Otto to test the bot, or open a bad answer in Conversations and click Ask Otto about this chat to find out whether the prompt or the knowledge is at fault. For a routine after launch, see Improve your bot's answers.

Common mistakes

• Pasting knowledge into the prompt. Long product lists or FAQs belong in data sources, which only send the relevant parts.
• Rules that contradict each other, such as "always be brief" and "always explain in detail". The bot picks one unpredictably.
• Vague rules. "Be helpful" changes nothing. "Keep answers under three sentences" does.
• Naming a power-up that isn't turned on, or using a different name from its card.
• Only saying what not to do. Pair every "don't" with what to do instead.
• Rewriting everything at once. Change one rule, test it, then move on.
• Heavy formatting on plain-text channels. See Format answers for each channel.

Troubleshooting

The bot makes things up

Add the rule from Answer only from your knowledge and lower Creativity (temperature). If the answer is in your data sources but the bot can't find it, the problem is retrieval: see Retrieval settings.

The bot ignores part of the prompt

Move the rule nearer the top, make it short and specific, and remove anything that contradicts it. A very long prompt dilutes every rule in it.

The bot never uses a power-up

Check the power-up is turned on and your model supports power-ups. Then make its Description say when to use it, and add a rule to the prompt that uses its exact Power-up name.

I see "System message" and "Initial prompt" instead of "Prompt"

Your bot uses an older configuration that split the prompt into two fields. Click Click here to migrate to the latest version above the fields, check the combined prompt in the Bot migration wizard, then click Migrate your bot and Update bot.