> ## Documentation Index
> Fetch the complete documentation index at: https://chatbotx.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Dynamic Content

> A detailed guide to Dynamic Content in ChatbotX: standard JSON structure, creating visual interactive messages, and executing automated Actions.

**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:

```json theme={null}
{
  "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:

```json theme={null}
{
    "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:

```json theme={null}
{
    "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.

```json theme={null}
{
    "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.

```json theme={null}
{
   "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).

```json theme={null}
{
    "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`.

```json theme={null}
{
    "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:

```json theme={null}
{
    "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": []
            }
        }
    ]
}
```

### Send a Gallery

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.

```json theme={null}
{
    "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.

```json theme={null}
{   
    "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:

```json theme={null}
{
    "messages": [],
    "actions": [
        {
            "action": "add_tag",
            "tag_name": "hot-lead"
        }
    ]
}
```

### Remove Tag

Removes a classification label (Tag) from the contact:

```json theme={null}
{
    "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`):

```json theme={null}
{
    "messages": [],
    "actions": [
        {
            "action": "set_field_value",
            "field_name": "phone",
            "value": "0912345678"
        }
    ]
}
```

### Unset Custom Field

Clears the saved value inside a Custom Field:

```json theme={null}
{
    "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:

```json theme={null}
{
    "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:

```json theme={null}
{
    "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:

```json theme={null}
{
    "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:

```json theme={null}
{
    "messages": [],
    "actions": [
        {
            "action": "unassign_conversation"
        }
    ]
}
```

### Combine multiple actions

You can combine and execute multiple actions simultaneously in a single response payload:

```json theme={null}
{
    "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:

```json theme={null}
{
    "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

<CardGroup cols={2}>
  <Card title="Via External API Request (Webhook)" icon="server">
    Use in Flow Builder workflows when connecting to CRM, ERP, Google Sheets, or custom backend servers.
  </Card>

  <Card title="Via AI Agent (Rich Responses)" icon="bot">
    Configure directly inside the System Message (Prompt) of an AI Agent to output visual interfaces and execute actions dynamically.
  </Card>
</CardGroup>

### 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.

<Steps>
  <Step title="Add External API Request Action">
    In Flow Builder, select **Actions > External API Request**.
  </Step>

  <Step title="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).
  </Step>

  <Step title="Enable Dynamic Content Response">
    Under Response settings, enable **Dynamic Content** mode. Your server will return a JSON object containing `messages` and `actions` arrays.
  </Step>

  <Step title="Test and Publish">
    Click **Test Request** to verify data returned from your server, then save the Flow and publish for live use.
  </Step>
</Steps>

### 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](/ai-agents/rich-responses) guide.

```text theme={null}
# 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

<Note>
  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.
</Note>

<Warning>
  **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.
</Warning>

<Warning>
  **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.
</Warning>

<Note>
  **API Rate Limit:** The default API rate limit is 100 requests per 60 seconds per bot account.
</Note>