← Back to docsGuide

Quick-reply buttons for your AI agent

Let customers tap a button instead of typing. You define buttons inside your agent's Instructions, and the agent attaches them to its replies. WhatsApp shows up to 3 tappable buttons per message.

Seeing "→ attach" in your messages?

That means button markers were written inline with text (for example → attach @bm-btn {value:"200ml"}). The marker becomes a button but the leftover words stay visible. Put each marker alone on its own line at the end of the reply — see Common mistakes.

How it works in two parts

Define your buttons once, anywhere in the Instructions.
Tell the agent when to attach them, using the button's value.

1. Define buttons

Add one line per button. Each button has a name (the label the customer sees, max 20 characters) and a value (a short stable id you reference in your rules):

@bm-btn {name:"Track my order", value:"track_order"}
@bm-btn {name:"Talk to a human", value:"handoff"}

Optionally group buttons into a named menu so you can attach the whole set with one line:

@bm-menu {id:"main", buttons:"track_order, handoff"}

2. Attach buttons in a reply

In your rules, tell the agent to end its reply with the marker(s). Use only the value when attaching:

When the customer asks about their order, reply with a short line
and then attach the menu:
@bm-menu {id:"main"}

Or attach individual buttons:

@bm-btn {value:"track_order"}
@bm-btn {value:"handoff"}

3. Handle the tap

When a customer taps a button, the agent receives their message ending with [button:<value>]. Write a rule for each value:

If the message contains [button:track_order], ask for the order number.
If the message contains [button:handoff], hand off to a human teammate.

Rules & limits

Max 3 buttons per message (WhatsApp limit). Extra ones are dropped.
Labels are capped at 20 characters.
Only values you defined are sent; unknown values are ignored.
Markers are removed before the customer sees the message — they never see @bm-btn.

Full worked example

A product-picker flow (like a coconut-oil store). Paste this style into your agent's Instructions and adapt the names/values:

You are the shop assistant for CocoGlow.

# Buttons
@bm-btn {name:"Coconut Oils", value:"cat_coconut"}
@bm-btn {name:"Cooking Oils", value:"cat_cooking"}
@bm-btn {name:"Best Sellers", value:"cat_best"}
@bm-btn {name:"200 ml", value:"size_200"}
@bm-btn {name:"250 ml", value:"size_250"}
@bm-btn {name:"500 ml", value:"size_500"}
@bm-menu {id:"categories", buttons:"cat_coconut, cat_cooking, cat_best"}
@bm-menu {id:"sizes", buttons:"size_200, size_250, size_500"}

# Flow
When the customer wants to buy, reply "What are you looking for? 🛒"
and attach the categories menu. End the reply with this line and nothing else:
@bm-menu {id:"categories"}

When they pick a category ([button:cat_coconut] etc.), show the products,
then ask "Choose a size 👇" and end with:
@bm-menu {id:"sizes"}

When they pick a size ([button:size_200] etc.), show the price and offer.

Notice every @bm-menu / @bm-btn line stands alone at the end of the reply — no "attach", no arrows, no extra words around it.

Common mistakes

❌ Don't	✅ Do
`→ attach @bm-btn {value:"size_200"}` Leaves "→ attach" visible.	`@bm-btn {value:"size_200"}` Marker alone on its own line.
Writing the label when attaching: `@bm-btn {name:"200 ml"}`	Use the value when attaching: `@bm-btn {value:"size_200"}`
Attaching a value you never defined.	Define every button once before attaching it.
Offering 5+ buttons in one message.	Keep it to 3; use a follow-up message or a menu for more.

Test before going live

Open your agent, scroll to the Test playground, and send a message that should trigger buttons. The reply preview shows the buttons that will be attached and the exact text the customer will see — confirm there is no stray "attach" text before saving.

Manage buttons on the Agents page → open an agent → Quick reply buttons.