botserver/docs/src/chapter-05/keyword-add-suggestion.md

ADD_SUGGESTION

Add conversational suggestions or quick reply options for user interactions.

Syntax

ADD_SUGGESTION text AS value

Parameters

Parameter	Type	Description
text	String	Display text shown to the user
value	String	Value sent when suggestion is clicked

Description

The ADD_SUGGESTION keyword adds quick reply buttons or suggestion chips to the conversation interface. These provide users with:

• Quick action buttons
• Common response options
• Guided conversation paths
• Menu-like interactions
• Context-aware suggestions

Suggestions appear as clickable elements in supported channels (web, WhatsApp, Teams, etc.).

Examples

Basic Suggestions

ADD_SUGGESTION "Yes" AS "confirm"
ADD_SUGGESTION "No" AS "decline"
ADD_SUGGESTION "Maybe later" AS "postpone"
answer = HEAR "Would you like to proceed?"

Dynamic Suggestions from Data

departments = ["Sales", "Support", "Billing", "Technical"]
FOR EACH dept IN departments
    ADD_SUGGESTION dept AS dept
NEXT
selection = HEAR "Which department do you need?"

Context-Based Suggestions

IF user_type = "new" THEN
    ADD_SUGGESTION "Get Started" AS "onboarding"
    ADD_SUGGESTION "View Tutorial" AS "tutorial"
    ADD_SUGGESTION "Contact Support" AS "help"
ELSE
    ADD_SUGGESTION "Check Status" AS "status"
    ADD_SUGGESTION "New Request" AS "create"
    ADD_SUGGESTION "View History" AS "history"
END IF

Menu System

' Main menu
CLEAR_SUGGESTIONS
ADD_SUGGESTION "Products" AS "menu_products"
ADD_SUGGESTION "Services" AS "menu_services"
ADD_SUGGESTION "Support" AS "menu_support"
ADD_SUGGESTION "About Us" AS "menu_about"

choice = HEAR "What would you like to know about?"

IF choice = "menu_products" THEN
    CLEAR_SUGGESTIONS
    ADD_SUGGESTION "Pricing" AS "product_pricing"
    ADD_SUGGESTION "Features" AS "product_features"
    ADD_SUGGESTION "Compare" AS "product_compare"
    ADD_SUGGESTION "Back" AS "menu_main"
END IF

Channel Support

Channel	Display Type	Limitations
Web	Buttons/Chips	Up to 10 suggestions
WhatsApp	Reply Buttons	Max 3 buttons
Teams	Hero Cards	Unlimited
Slack	Block Actions	Up to 5 per block
SMS	Numbered List	Text-only fallback

Suggestion Persistence

Suggestions remain active until:

• User clicks one
• CLEAR_SUGGESTIONS is called
• New suggestions replace them
• Conversation ends
• Timeout occurs (configurable)

Styling and Appearance

Suggestions adapt to channel capabilities:

• Rich Channels: Styled buttons with icons
• Basic Channels: Numbered text options
• Voice: Read as options list

Return Value

The keyword itself returns true if suggestion was added successfully, false otherwise.

When user clicks a suggestion, the value is returned to the next HEAR command.

Memory Management

Suggestions are stored in session cache:

• Each session maintains its own suggestion list
• Cleared automatically on session end
• Can store up to 50 suggestions per session

Best Practices

1. Clear Before Adding: Always clear old suggestions when changing context
2. Limit Options: Keep to 3-5 suggestions for better UX
3. Descriptive Text: Make suggestion text clear and actionable
4. Meaningful Values: Use values that are easy to handle in code
5. Provide Escape: Always include a "Back" or "Cancel" option
6. Mobile First: Consider mobile screen sizes

Advanced Features

Suggestion Groups

' Group related suggestions
ADD_SUGGESTION "Small ($10)" AS "size:small"
ADD_SUGGESTION "Medium ($15)" AS "size:medium"
ADD_SUGGESTION "Large ($20)" AS "size:large"

Conditional Display

IF has_permission("admin") THEN
    ADD_SUGGESTION "Admin Panel" AS "admin"
END IF

Localized Suggestions

language = GET_USER_LANGUAGE()
IF language = "es" THEN
    ADD_SUGGESTION "Sí" AS "yes"
    ADD_SUGGESTION "No" AS "no"
ELSE
    ADD_SUGGESTION "Yes" AS "yes"
    ADD_SUGGESTION "No" AS "no"
END IF

Error Handling

• Silently fails if suggestion limit exceeded
• Logs warning if value is too long
• Falls back to text input if channel doesn't support suggestions

Related Keywords

• CLEAR_SUGGESTIONS - Remove all suggestions
• HEAR - Wait for user input (including suggestion clicks)
• TALK - Send message with suggestions
• FORMAT - Format suggestion text

Implementation

Located in src/basic/keywords/add_suggestion.rs

Uses Redis cache for storage when available, falls back to in-memory storage.