> ## Documentation Index > Fetch the complete documentation index at: https://docs.theomnibot.io/llms.txt > Use this file to discover all available pages before exploring further. # Rich Responses: Cards, Carousels, and Automated Actions > Enable AI Agents to send interactive cards, carousels, and quick replies, and execute automated actions like tagging contacts or triggering flows. Rich Responses transform your AI Agent from a plain-text responder into a fully interactive, channel-aware messaging experience. Instead of sending walls of text, an Agent with Rich Responses enabled can display visual product cards, horizontally scrollable carousels, quick-reply buttons, and images — all automatically formatted for the channel the customer is on (Messenger, Instagram, WhatsApp, Zalo, Webchat, and others). At the same time, the Agent can silently execute system actions in the background: assigning Tags, updating Custom Fields, triggering automation Flows, or handing the conversation to a human agent. Standard AI models can only output raw text. Without Rich Responses, if a customer asks to see a product, the Agent can only share a link. With Rich Responses, ChatbotX acts as a middleware layer that reads the Agent's structured JSON output and renders it as native interactive components on each channel — no extra code required on your side. ## When to Use Rich Responses Rich Responses are particularly valuable in these scenarios: * **Product or service consultations** that require displaying images, names, prices, and direct purchase buttons. * **Mobile-friendly interactions** where Quick Replies reduce typing effort and guide the customer through a decision. * **Lead capture flows** where the Agent collects an email, phone number, or full name and automatically saves it to a Custom Field. * **Customer segmentation** where the Agent assigns Tags (`lead`, `hot-lead`, `vip`, `support-needed`) based on how the conversation unfolds. * **Advanced automations** where the Agent triggers a Flow or transfers the chat to a live agent for special or sensitive requests. ## Response Types | Type | Description | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Card** | A single panel showing a product or service image, title, short description, and an action button. Ideal for answering a question about one specific item. | | **Carousel** | A horizontally scrollable collection of 2–4 Cards. Ideal for presenting a product line or a set of service options. | | **Quick Replies** | Tappable buttons displayed beneath a message that let the customer choose an option without typing (e.g., Size S, Size M, Size L, Size XL). | | **Image** | A standalone image message, useful for sending actual product photos. | | **Actions** | Background operations the Agent executes alongside a message — see the Actions table below. | ### Available Actions | Action | Effect | | -------------------------- | ---------------------------------------------------------------------------------- | | `add_tag` | Assigns a Tag to the contact (e.g., `add_tag: hot-lead`). | | `remove_tag` | Removes a Tag from the contact (e.g., `remove_tag: hot-lead`). | | `set_field_value` | Updates a Custom Field with a value (e.g., `set_field_value: buyer_status = hot`). | | `unset_field_value` | Clears the value of a Custom Field (e.g., `unset_field_value: order_detail`). | | `send_flow` | Triggers an automation Flow by its ID (e.g., `send_flow: 11592463518629888`). | | `transfer_conversation_to` | Hands the conversation to a human agent (e.g., `transfer_conversation_to: human`). | ## How to Enable Rich Responses Go to **ChatbotX System Settings** and create the Custom Fields (e.g., `size`, `color`, `address`, `buyer_status`) and Tags (e.g., `lead`, `hot-lead`, `support-needed`) your business needs before configuring the Agent. Select **AI Agents** from the left navigation bar. Click edit on an existing Agent or create a new one. In the Agent configuration modal, scroll down to the **Rich Response** toggle and switch it to **ON**. With this setting active, the Agent outputs a structured JSON object containing `messages` and `actions` instead of raw text streaming. Copy the production-ready Prompt template (see below) and paste it into the **System Message (Prompt)** field. Customise the business name, product catalogue, Custom Field names, Tag names, and Flow IDs to match your workspace. Click **Confirm** (or **Save Settings**) and send a test message through a live conversation channel to verify that cards, carousels, and quick replies render correctly. You **must** create every Custom Field and Tag in ChatbotX System Settings before referencing them in the Prompt. If a field or tag does not exist in the system, the Agent will not be able to save or assign values to it. ## How Response Rules Work in the System Message When Rich Responses is enabled, the Agent must output valid JSON in this shape for every reply: ```json theme={null} { "messages": [...], "actions": [...] } ``` The `messages` array contains the visual components (text, card, carousel, quick replies, image). The `actions` array contains the background operations (tag assignment, field updates, flow triggers, human transfer). You define the rules for when each response type should be used directly in the System Message — the Agent reads those rules and applies them automatically based on the customer's intent. ## Production Prompt Template The template below is a complete, production-grade Prompt designed for an automated fashion sales Agent. You can copy it directly, then adapt the brand name, product catalogue, field names, tag names, and Flow IDs to fit your own workspace. ```text theme={null} # Prompt: Fashion Sales Assistant "Noname" You are an AI sales assistant on the Facebook Fanpage of the premium fashion brand **Noname**. Addressing rules: Address the customer as {{gender}} and refer to yourself as "I". # MANDATORY OUTPUT RULES (CRITICAL) 1. 100% of your responses MUST strictly follow valid Messenger Messaging Platform JSON structure ({"messages":[...], "actions":[...]}). 2. ABSOLUTELY DO NOT send plain text responses or pure Markdown without wrapping them in JSON format. 3. When customers ask for product details -> MUST return a JSON Service Card (Generic Template). 4. When customers ask about Size / Color / Want to select size -> MUST return a message with a `quick_replies` array (Size S, Size M, Size L, Size XL). NEVER reply with "no size information available" or ask back in plain text. # Product Catalog & Fixed Specifications - Look up in file_search # Response Rules by Scenario ## 1. Initiating the Conversation - Greet {{gender}} politely and warmly. - DO NOT ask generic questions like "What does {{gender}} need?" or "How can I help {{gender}}?". - Proactively suggest featured products from the catalog above. ## 2. Customer asks for details or price of 1 specific product - MUST return a **Service Card** message. - Card includes: Product image, Product name + Product code, Short description + Listed price, "Order Now" button. - `actions` array: `[]` (empty, no tags added or fields set yet). ## 3. Customer wants to view multiple products or a product list - Display a **Carousel** (`template_type: "generic"`) with 2-4 products. - Each Carousel card includes: Product image, Product name, Short description + Price, "Order Now" button. - `actions` array: `[]`. ## 4. Customer asks about Size, Color, or wants to choose Size - MUST immediately display a message with **Quick Replies** for size selection (`Size S`, `Size M`, `Size L`, `Size XL`). - NEVER ask the customer back or say "no size info". - When {{gender}} selects size/color: Update corresponding Custom Fields (`size = M`, `color = Navy`). DO NOT assign lead tags at this step. ## 5. Customer wants to see actual product photos - Send an Image message containing the product image URL from the catalog above. ## 6. Customer confirms order placement & provides information - Collect 3 items: Full name, Phone number (accepting formats starting with "0" or "+84"), Delivery address. - Save to correct fields: + Full name -> `full_name` + Phone number -> `phone` + Address -> `address` ## 7. Customer confirms final order placement - Re-confirm order details (Product - Size - Color - Quantity). - `actions` array MUST contain: + `add_tag: hot-lead` + `set_field_value: buyer_status = hot` + `set_field_value: order_detail = ` + `send_flow: 11592463518629888` - Announce estimated delivery time: Northern region: 2-4 days, Central region: 3-5 days, Southern region: 4-6 days. ## 8. Customer wants to cancel order - Gently ask for the reason to assist. - If customer decides to cancel: + `remove_tag: hot-lead` + `unset_field_value: order_detail` + `add_tag: order-cancelled` ## 9. Complaint / Request for Human Agent - Send a message notifying that a staff member will take over immediately. - Actions: `add_tag: support-needed`, `transfer_conversation_to: human`. # Workspace (Variables Declaration) ## Custom Fields - size - color - buyer_status - order_detail - address - interest ## System Fields - full_name - phone ## Tags - lead - hot-lead - order-cancelled - support-needed - browsing ## Flow - Flow ID: `11592463518629888` # Guidelines - Respond flexibly in English or Vietnamese based on customer language. - Concise, clear, and friendly. - Do not apply tags or update fields when customer is only inquiring for options. - Only update lead status after customer confirms purchase or provides order info. ``` ## Best Practices Rich Message formats (Card, Carousel, Quick Replies) are automatically optimised by ChatbotX for each conversation channel. A Carousel renders as a standard Facebook Carousel on Messenger, and as a compatible visual list on Zalo or WhatsApp — you do not need to write separate prompts for different channels. When writing your Prompt rules, keep the following in mind: * **Flow IDs, Tag names, and Custom Field names** in the `actions` array must exactly match what you created in ChatbotX System Settings. A mismatch will silently fail — the Agent will send the message but the action will not execute. * **Keep rule sections short and explicit.** The more clearly each scenario is defined, the more reliably the Agent will produce the correct JSON structure. * **Test on the actual channel.** Preview rendering inside ChatbotX may differ from how a channel like WhatsApp or Instagram displays the components. Always test on a live channel before launching.