Skip to main content
Dynamic Content is an advanced feature that allows ChatbotX to automatically generate and render visual interactive interface messages (such as product Cards, horizontal Carousels, Buttons, Quick Replies, media) while executing automated system Actions based on real-time JSON payloads returned from an external API or AI Agent model. Typically, when integrating inventory management systems, CRMs, e-commerce websites, or AI with a chatbot, displaying dynamic information (such as customer-specific product recommendations, account balances, or order statuses) can be challenging because each conversation channel (Messenger, Zalo, WhatsApp) has different UI formatting rules. Dynamic Content solves this problem completely by providing a unified JSON structure. ChatbotX automatically translates this JSON payload into the native interactive interface for each specific messaging platform.

​
When to Use Dynamic Content

Dynamic Content is the ideal solution for businesses in advanced automation scenarios:
  • Inventory and Catalog Integration: Look up and display live product catalogs, stock availability, and prices directly from your server or website inside the chatbot.
  • AI Agent Integration: Configure AI Agents to return rich responses (Rich Responses) as visual Cards or Carousels with instant order buttons.
  • Personalized Data Updates: Retrieve appointments, loyalty points, discount codes, or order tracking statuses customized for each contact.
  • Automated Segmentation and Routing: Deliver visually appealing messages while simultaneously applying Tags, updating Custom Fields, or transferring chats to live support agents.

​
Standard JSON Data Structure Overview

Dynamic Content payloads must be wrapped inside a valid JSON object containing 2 primary arrays at the root level: 
{
  "messages": [],
  "actions": []
}
  • messages: Contains the list of messages displayed directly to the end user. You can send one or multiple sequential messages within this array.
  • actions: Contains management commands executed immediately by ChatbotX when messages are dispatched.
Note: ChatbotX automatically attaches the user ID in the HTTP Header of every request sent to your server as X-USER-ID. You can use this value to identify the interacting contact.

​
Supported Message Templates (messages)

The messages array supports all standard message formats to display to the user. Here are the detailed JSON structure templates:

​
Send a text message

Template to send a simple text message to the contact: 
{
    "messages": [
        {           
            "message": {
                "text": "Hello! How can I help you today?",
                "quick_replies": []
            }
        }
    ]
}

​
Sending more than a single message

Template to send two or more sequential text messages in a single response: 
{
    "messages": [
        {
            "message": {
                "text": "First message: Hello!"
            }
        },
        {
            "message": {
                "text": "Second message: Here is your detailed information.",
                "quick_replies": []
            }
        }
    ]
}

​
Sending a text message with buttons

A text message can contain up to 3 buttons. The title of each button supports a maximum length of 20 characters. There are 3 common types of buttons:
  • web_url: Opens a website link.
  • postback: Triggers a Flow or executes an automated action by supplying a Flow ID or a JSON Action object as the payload.
  • phone_number: Places a call to a pre-configured phone number.
{
    "messages": [
        {
            "message": {
                "attachment": {
                    "payload": {
                        "buttons": [
                            {
                                "title": "Open Website",
                                "type": "web_url",
                                "url": "https://chatbotx.vn"
                            },
                            {
                                "title": "Claim Gift",
                                "payload": "FLOW_OR_STEP_ID",
                                "type": "postback"
                            },
                            {
                                "title": "Call Hotline",
                                "type": "phone_number",
                                "payload": "+84912345678"
                            }
                        ],
                        "template_type": "button",
                        "text": "Please select one of the options below:"
                    },
                    "type": "template"
                },
                "quick_replies": []
            }            
        }
    ]
}

​
Sending a message with quick replies

Quick replies display right below the text message and disappear after the user clicks one. The platform supports a maximum of 11 quick replies per message. You can use Flow IDs or Step IDs as payloads. 
{
   "messages": [
       {           
           "message": {
               "text": "Which topic do you need help with?",
               "quick_replies": [
                  {
                     "content_type": "text",
                     "title": "Product Inquiry",
                     "payload": "FLOW_OR_STEP_ID_1"
                  },
                  {
                     "content_type": "text",
                     "title": "Request Quote",
                     "payload": "FLOW_OR_STEP_ID_2"
                  }
               ]
           }
       }
   ]
}

​
Send an image, video, audio, file

You can send media files by changing the value of type inside the attachment object to image, video, audio, or file (document files like PDF/Doc). 
{
    "messages": [
        {
            "message": {
                "attachment": {
                    "type": "image",
                    "payload": {
                        "url": "https://chatbotx.vn/images/banner.png"
                    }
                },
                "quick_replies": []
            }
        }
    ]
}

​
Send a single Card

A single card (Generic Template) displays an image, a title, and a brief description. Both the title and description support a maximum length of 80 characters. The value for the image_aspect_ratio property can be set to horizontal or square. 
{
    "messages": [
        {
            "message": {
                "attachment": {
                    "payload": {
                        "elements": [
                            {
                                "title": "Featured Product Name",
                                "subtitle": "A short summary of features and pricing details.",
                                "image_url": "https://chatbotx.vn/images/product.png"
                            }
                        ],
                        "template_type": "generic",
                        "image_aspect_ratio": "horizontal"
                    },
                    "type": "template"
                },
                "quick_replies": []
            }
        }
    ]
}

​
Send a single Card with buttons

A single product card supports attaching up to 3 interactive buttons below the content: 
{
    "messages": [
        {
            "message": {
                "attachment": {
                    "payload": {
                        "elements": [
                            {
                                "title": "AI Automation Course",
                                "subtitle": "Learn how to automate your business processes with AI Agents.",
                                "image_url": "https://chatbotx.vn/images/course.png",
                                "buttons": [
                                    {
                                        "title": "Course Details",
                                        "type": "web_url",
                                        "url": "https://chatbotx.vn/course"
                                    },
                                    {
                                        "title": "Register Now",
                                        "payload": "FLOW_OR_STEP_ID",
                                        "type": "postback"
                                    },
                                    {
                                        "title": "Consult Zalo",
                                        "type": "phone_number",
                                        "payload": "+84912345678"
                                    }
                                ]
                            }
                        ],
                        "template_type": "generic",
                        "image_aspect_ratio": "horizontal"
                    },
                    "type": "template"
                },
                "quick_replies": []
            }
        }
    ]
}
A gallery (Carousel) is a collection of cards placed side by side, allowing users to scroll horizontally to view options. A gallery supports up to 10 product cards. 
{
    "messages": [
        {
            "message": {
                "attachment": {
                    "payload": {
                        "elements": [
                            {
                                "title": "Product A",
                                "subtitle": "Brief description of Product A.",
                                "image_url": "https://chatbotx.vn/images/prod_a.png",
                                "buttons": []
                            },
                            {
                                "title": "Product B",
                                "subtitle": "Brief description of Product B.",
                                "image_url": "https://chatbotx.vn/images/prod_b.png",
                                "buttons": []
                            }
                        ],
                        "template_type": "generic",
                        "image_aspect_ratio": "horizontal"
                    },
                    "type": "template"
                },
                "quick_replies": []
            }
        }
    ]
}

​
Send messages supported only by WhatsApp

The WhatsApp channel supports unique message formats not available on other platforms, such as Interactive Button Messages. The JSON payload must strictly follow the format defined in the WhatsApp Cloud API documentation. ChatbotX automatically populates the recipient parameter to before sending the message. 
{   
    "messages": [
        {
            "messaging_product": "whatsapp",
            "recipient_type": "individual",
            "to": null,
            "type": "interactive",
            "interactive": {
                "type": "button",
                "body": {
                    "text": "Please select an option below to confirm:"
                },
                "action": {
                    "buttons": [
                        {
                            "type": "reply",
                            "reply": {
                                "id": "FLOW_OR_STEP_ID_1",
                                "title": "Confirm Booking"
                            }
                        },
                        {
                            "type": "reply",
                            "reply": {
                                "id": "FLOW_OR_STEP_ID_2",
                                "title": "Cancel Booking"
                            }
                        }
                    ]
                }
            }
        }
    ]
}

​
Execute actions while sending messages

The actions array allows you to send control commands to instruct the system to automatically process contact information as soon as the message response is sent. Below are the supported actions:

​
Add Tag

Assigns a classification label (Tag) to the contact: 
{
    "messages": [],
    "actions": [
        {
            "action": "add_tag",
            "tag_name": "hot-lead"
        }
    ]
}

​
Remove Tag

Removes a classification label (Tag) from the contact: 
{
    "messages": [],
    "actions": [
        {
            "action": "remove_tag",
            "tag_name": "old-lead"
        }
    ]
}

​
Set Custom Field

Writes a new value to a Custom Field or system field (such as phone, email, full_name, first_name, last_name): 
{
    "messages": [],
    "actions": [
        {
            "action": "set_field_value",
            "field_name": "phone",
            "value": "0912345678"
        }
    ]
}

​
Unset Custom Field

Clears the saved value inside a Custom Field: 
{
    "messages": [],
    "actions": [
        {
            "action": "unset_field_value",
            "field_name": "order_detail"
        }
    ]
}

​
Send Flow

Triggers an automated script flow (Flow) by its numeric ID. You can copy this ID from the Flow link in the Flow list page: 
{
    "messages": [],
    "actions": [
        {
            "action": "send_flow",
            "flow_id": "5854739484"
        }
    ]
}

​
Transfer conversation to human

Transfers the conversation state from chatbot automated handling to the live agent support queue: 
{
    "messages": [],
    "actions": [
        {
            "action": "transfer_conversation_to",
            "value": "human"
        }
    ]
}

​
Assign conversation to admin

Assigns the conversation directly to a specific Admin ID for management and response: 
{
    "messages": [],
    "actions": [
        {
            "action": "assign_conversation",
            "admin_id": "12345"
        }
    ]
}

​
Unassign conversation

Removes the currently assigned Admin and returns the conversation back to the unassigned general queue: 
{
    "messages": [],
    "actions": [
        {
            "action": "unassign_conversation"
        }
    ]
}

​
Combine multiple actions

You can combine and execute multiple actions simultaneously in a single response payload: 
{
    "messages": [],
    "actions": [
        {
            "action": "set_field_value",
            "field_name": "phone",
            "value": "0912345678"
        },
        {
            "action": "send_flow",
            "flow_id": "5854739484"
        }
    ]
}

​
Use actions as a payload of buttons and quick replies

Since the payload property of a button or Quick Reply requires a string data type, you need to serialize the object containing the actions array into a JSON string. Here is an example button structure invoking the Send Flow action upon click: 
{
    "messages": [
        {
            "message": {
                "attachment": {
                    "payload": {
                        "buttons": [
                            {
                                "title": "Start Now",
                                "payload": "{\"actions\":[{\"action\":\"send_flow\",\"flow_id\":\"5854739484\"}]}",
                                "type": "postback"
                              }
                        ],
                        "template_type": "button",
                        "text": "Click the button below to trigger the automation script:"
                    },
                    "type": "template"
                },
                "quick_replies": []
            }            
        }
    ]
}

​
2 Implementation Methods for Dynamic Content

Via External API Request (Webhook)

Use in Flow Builder workflows when connecting to CRM, ERP, Google Sheets, or custom backend servers.

Via AI Agent (Rich Responses)

Configure directly inside the System Message (Prompt) of an AI Agent to output visual interfaces and execute actions dynamically.

​
Method 1: Use in Flow Builder (External API Request)

In the conversation script editor (Flow Builder), use an External API Request action block to send HTTP requests (GET or POST) to your backend server. Your server processes logic and returns a response formatted as Dynamic Content JSON.
1

Add External API Request Action

In Flow Builder, select Actions > External API Request.
2

Configure Endpoint URL and Method

Enter your server Webhook URL (Endpoint URL), select method (POST or GET), and supply required Header parameters (such as API Key or Authorization token).
3

Enable Dynamic Content Response

Under Response settings, enable Dynamic Content mode. Your server will return a JSON object containing messages and actions arrays.
4

Test and Publish

Click Test Request to verify data returned from your server, then save the Flow and publish for live use.

​
Method 2: Configure for AI Agents (Rich Responses)

Paste the Dynamic Content JSON output rules into the System Message (Prompt) field of your AI Agent. During customer conversations, the AI Agent acts as an intelligent server generating Dynamic Content JSON payloads for ChatbotX to render. For detailed instructions and production-ready Prompt templates, refer to the Rich Responses guide. 
# Dynamic Content Output Rules

You are an AI Agent that MUST always return responses in valid JSON format adhering to ChatbotX Dynamic Content structure:
{"messages": [...], "actions": [...]}

Rules:
1. Root must contain only 2 arrays: "messages" and "actions".
2. When consulting on products: Return Service Card messages (Generic Template) in the "messages" array.
3. When customer confirms purchase: Return confirmation messages in the "messages" array and add_tag, set_field_value, send_flow commands in the "actions" array.
4. Output valid JSON only, without any explanatory text outside the JSON block.

​
Best Practices and System Limits

When using External Requests to fetch data from your custom server, ChatbotX automatically attaches the user ID in the HTTP Header as X-USER-ID. You can use this Header to identify the specific contact interacting with your server.
Important Note on Custom Fields: To allow the system to save data to a Custom Field using set_field_value, you must create that Custom Field in ChatbotX System Settings beforehand. If the field has not been initialized, the Action command will be skipped.
Valid JSON Format: Ensure the JSON payload returned from your server or AI Agent is always valid JSON. Syntax errors (such as missing brackets or incorrect commas) will prevent messages from rendering to end users.
API Rate Limit: The default API rate limit is 100 requests per 60 seconds per bot account.