Chuyển đến nội dung chính
Dynamic Content là tính năng cao cấp cho phép ChatbotX tự động tạo và hiển thị các tin nhắn giao diện tương tác (như thẻ sản phẩm Card, bộ sưu tập Carousel, nút bấm Buttons, Quick Replies, hình ảnh) đồng thời thực thi các hành động hệ thống ngầm (Actions) dựa trên dữ liệu JSON trả về thời gian thực từ API bên ngoài hoặc mô hình AI Agent. Thông thường, khi tích hợp hệ thống quản lý kho, CRM, website bán hàng hoặc AI với chatbot, việc hiển thị thông tin động (như danh sách sản phẩm theo từng khách hàng, số dư tài khoản hay trạng thái đơn hàng) gặp khó khăn vì mỗi kênh trò chuyện (Messenger, Zalo, WhatsApp) có giao diện hiển thị khác nhau. Dynamic Content giải quyết triệt để vấn đề này bằng cách cung cấp một cấu trúc JSON chuẩn chung. ChatbotX tự động biên dịch dữ liệu JSON này thành giao diện tin nhắn chuẩn nhất trên từng kênh trò chuyện của khách hàng.

​
Khi nào bạn cần sử dụng Dynamic Content?

Dynamic Content là giải pháp tối ưu cho doanh nghiệp trong các kịch bản tự động hóa nâng cao:
  • Tra cứu và cập nhật dữ liệu kho bãi: Hiển thị danh sách sản phẩm, tồn kho, giá bán trực tiếp từ máy chủ hoặc website của bạn lên chatbot.
  • Tích hợp mô hình AI Agent: Cấu hình AI Agent trả về câu trả lời giàu tương tác (Rich Responses) dưới dạng thẻ Card hoặc Carousel kèm các nút bấm đặt hàng.
  • Cá nhân hóa trải nghiệm khách hàng: Tra cứu lịch hẹn, điểm tích lũy, mã giảm giá hoặc trạng thái vận chuyển đơn hàng riêng cho từng liên hệ.
  • Tự động phân loại và điều hướng: Vừa gửi tin nhắn giao diện đẹp mắt cho khách hàng, vừa tự động gán Tag, cập nhật Custom Field hoặc chuyển chat cho nhân viên tư vấn cùng lúc.

​
Cấu trúc dữ liệu JSON tổng quan

Dữ liệu Dynamic Content bắt buộc đóng gói dưới một chuỗi JSON hợp lệ với 2 mảng đối tượng chính ở cấp gốc (root level): 
{
  "messages": [],
  "actions": []
}
  • messages: Chứa danh sách các tin nhắn hiển thị trực tiếp cho người dùng. Bạn có thể gửi một hoặc nhiều tin nhắn liên tiếp trong mảng này.
  • actions: Chứa các lệnh quản trị được hệ thống ChatbotX thực thi ngay lập tức khi tin nhắn được gửi đi.
Lưu ý: ChatbotX tự động đính kèm thông tin ID người dùng trong HTTP Header của mỗi HTTP Request gửi đến máy chủ của bạn dưới dạng X-USER-ID. Bạn có thể sử dụng thông tin này để xác định khách hàng tương tác.

​
Các mẫu tin nhắn được hỗ trợ (messages)

Mảng messages hỗ trợ tất cả các định dạng tin nhắn chuẩn để hiển thị cho người dùng. Dưới đây là các mẫu cấu trúc JSON chi tiết:

​
Gửi tin nhắn văn bản đơn thuần

Mẫu gửi một tin nhắn văn bản đơn giản đến khách hàng: 
{
    "messages": [
        {           
            "message": {
                "text": "Xin chào! Rất vui được hỗ trợ bạn.",
                "quick_replies": []
            }
        }
    ]
}

​
Gửi nhiều tin nhắn liên tiếp

Mẫu gửi hai hoặc nhiều tin nhắn văn bản nối tiếp nhau trong cùng một phản hồi: 
{
    "messages": [
        {
            "message": {
                "text": "Tin nhắn thứ nhất: Xin chào!"
            }
        },
        {
            "message": {
                "text": "Tin nhắn thứ hai: Đây là thông tin chi tiết của bạn.",
                "quick_replies": []
            }
        }
    ]
}

​
Gửi tin nhắn văn bản kèm nút bấm

Tin nhắn dạng văn bản có thể chứa tối đa 3 nút bấm. Tiêu đề của mỗi nút bấm hỗ trợ độ dài tối đa 20 ký tự. Có 3 loại nút bấm phổ biến:
  • web_url: Mở liên kết trang web.
  • postback: Kích hoạt một Flow hoặc gửi hành động tự động bằng cách điền ID của Flow hoặc mã JSON Action làm payload.
  • phone_number: Gọi đến số điện thoại cấu hình sẵn.
{
    "messages": [
        {
            "message": {
                "attachment": {
                    "payload": {
                        "buttons": [
                            {
                                "title": "Xem Website",
                                "type": "web_url",
                                "url": "https://chatbotx.vn"
                            },
                            {
                                "title": "Nhận Quà Ngay",
                                "payload": "FLOW_OR_STEP_ID",
                                "type": "postback"
                            },
                            {
                                "title": "Gọi Hotline",
                                "type": "phone_number",
                                "payload": "+84912345678"
                            }
                        ],
                        "template_type": "button",
                        "text": "Vui lòng chọn một trong các tùy chọn dưới đây:"
                    },
                    "type": "template"
                },
                "quick_replies": []
            }            
        }
    ]
}

​
Gửi tin nhắn kèm lựa chọn nhanh

Nút lựa chọn nhanh (Quick Replies) hiển thị ngay phía dưới tin nhắn thoại và sẽ biến mất sau khi khách hàng nhấn chọn. Hệ thống hỗ trợ tối đa 11 nút lựa chọn nhanh trong một tin nhắn. Bạn có thể sử dụng ID của Flow hoặc ID của Step làm payload. 
{
   "messages": [
       {           
           "message": {
               "text": "Bạn cần hỗ trợ về chủ đề nào dưới đây?",
               "quick_replies": [
                  {
                     "content_type": "text",
                     "title": "Tư vấn sản phẩm",
                     "payload": "FLOW_OR_STEP_ID_1"
                  },
                  {
                     "content_type": "text",
                     "title": "Báo giá dịch vụ",
                     "payload": "FLOW_OR_STEP_ID_2"
                  }
               ]
           }
       }
   ]
}

​
Gửi hình ảnh, video, âm thanh hoặc tệp tin

Bạn có thể gửi tệp truyền thông bằng cách thay đổi giá trị của type trong phần attachment thành image (hình ảnh), video (video), audio (âm thanh), hoặc file (tệp tin tài liệu như PDF/Doc). 
{
    "messages": [
        {
            "message": {
                "attachment": {
                    "type": "image",
                    "payload": {
                        "url": "https://chatbotx.vn/images/banner.png"
                    }
                },
                "quick_replies": []
            }
        }
    ]
}

​
Gửi thẻ sản phẩm đơn lẻ

Thẻ sản phẩm (Generic Template) hiển thị hình ảnh minh họa, tiêu đề và mô tả ngắn gọn. Tiêu đề và mô tả của thẻ hỗ trợ tối đa 80 ký tự. Giá trị tùy chọn của thuộc tính image_aspect_ratio là horizontal (tỷ lệ ngang) hoặc square (tỷ lệ vuông). 
{
    "messages": [
        {
            "message": {
                "attachment": {
                    "payload": {
                        "elements": [
                            {
                                "title": "Tên sản phẩm nổi bật",
                                "subtitle": "Mô tả ngắn gọn về tính năng và giá bán sản phẩm.",
                                "image_url": "https://chatbotx.vn/images/product.png"
                            }
                        ],
                        "template_type": "generic",
                        "image_aspect_ratio": "horizontal"
                    },
                    "type": "template"
                },
                "quick_replies": []
            }
        }
    ]
}

​
Gửi thẻ sản phẩm kèm nút bấm

Một thẻ sản phẩm hỗ trợ đính kèm tối đa 3 nút bấm tương tác trực tiếp phía dưới: 
{
    "messages": [
        {
            "message": {
                "attachment": {
                    "payload": {
                        "elements": [
                            {
                                "title": "Khóa học AI Automation",
                                "subtitle": "Học cách tự động hóa doanh nghiệp với AI Agent.",
                                "image_url": "https://chatbotx.vn/images/course.png",
                                "buttons": [
                                    {
                                        "title": "Chi tiết khóa học",
                                        "type": "web_url",
                                        "url": "https://chatbotx.vn/course"
                                    },
                                    {
                                        "title": "Đăng ký ngay",
                                        "payload": "FLOW_OR_STEP_ID",
                                        "type": "postback"
                                    },
                                    {
                                        "title": "Tư vấn qua Zalo",
                                        "type": "phone_number",
                                        "payload": "+84912345678"
                                    }
                                ]
                            }
                        ],
                        "template_type": "generic",
                        "image_aspect_ratio": "horizontal"
                    },
                    "type": "template"
                },
                "quick_replies": []
            }
        }
    ]
}
Bộ sưu tập (Carousel) thực chất là tập hợp nhiều thẻ sản phẩm xếp liền kề nhau cho phép khách hàng cuộn ngang để xem lựa chọn. Một bộ sưu tập hỗ trợ tối đa 10 thẻ sản phẩm. 
{
    "messages": [
        {
            "message": {
                "attachment": {
                    "payload": {
                        "elements": [
                            {
                                "title": "Sản phẩm A",
                                "subtitle": "Mô tả ngắn về sản phẩm A.",
                                "image_url": "https://chatbotx.vn/images/prod_a.png",
                                "buttons": []
                            },
                            {
                                "title": "Sản phẩm B",
                                "subtitle": "Mô tả ngắn về sản phẩm B.",
                                "image_url": "https://chatbotx.vn/images/prod_b.png",
                                "buttons": []
                            }
                        ],
                        "template_type": "generic",
                        "image_aspect_ratio": "horizontal"
                    },
                    "type": "template"
                },
                "quick_replies": []
            }
        }
    ]
}

​
Gửi tin nhắn riêng của WhatsApp

Kênh WhatsApp hỗ trợ một số kiểu tin nhắn đặc thù không có trên các kênh khác: ví dụ như Interactive Button Message (Tin nhắn nút bấm tương tác). Cấu trúc dữ liệu JSON cần tuân thủ đúng định dạng quy định của WhatsApp Cloud API. ChatbotX tự động gán thông tin người nhận vào tham số to trước khi gửi đi. 
{   
    "messages": [
        {
            "messaging_product": "whatsapp",
            "recipient_type": "individual",
            "to": null,
            "type": "interactive",
            "interactive": {
                "type": "button",
                "body": {
                    "text": "Vui lòng chọn một tùy chọn bên dưới để xác nhận:"
                },
                "action": {
                    "buttons": [
                        {
                            "type": "reply",
                            "reply": {
                                "id": "FLOW_OR_STEP_ID_1",
                                "title": "Xác nhận đặt lịch"
                            }
                        },
                        {
                            "type": "reply",
                            "reply": {
                                "id": "FLOW_OR_STEP_ID_2",
                                "title": "Hủy lịch hẹn"
                            }
                        }
                    ]
                }
            }
        }
    ]
}

​
Thực thi hành động tự động (actions)

Mảng actions cho phép bạn gửi các lệnh điều khiển để hệ thống tự động xử lý thông tin liên hệ của khách hàng ngay khi gửi phản hồi. Dưới đây là các hành động được hỗ trợ:

​
Thêm Tag

Gán một nhãn phân loại (Tag) cho khách hàng: 
{
    "messages": [],
    "actions": [
        {
            "action": "add_tag",
            "tag_name": "hot-lead"
        }
    ]
}

​
Xóa Tag

Gỡ bỏ một nhãn phân loại khỏi thông tin khách hàng: 
{
    "messages": [],
    "actions": [
        {
            "action": "remove_tag",
            "tag_name": "lead-cu"
        }
    ]
}

​
Cập nhật Custom Field

Ghi giá trị mới vào một trường dữ liệu tùy chỉnh (Custom Field) hoặc các trường thông tin hệ thống (như phone, email, full_name, first_name, last_name): 
{
    "messages": [],
    "actions": [
        {
            "action": "set_field_value",
            "field_name": "phone",
            "value": "0912345678"
        }
    ]
}

​
Xóa Custom Field

Xóa bỏ giá trị đã lưu trong một trường dữ liệu tùy chỉnh: 
{
    "messages": [],
    "actions": [
        {
            "action": "unset_field_value",
            "field_name": "order_detail"
        }
    ]
}

​
Kích hoạt Flow

Kích hoạt một luồng kịch bản tự động (Flow) bằng ID số cụ thể. Bạn có thể lấy ID này từ liên kết của Flow trong trang danh sách: 
{
    "messages": [],
    "actions": [
        {
            "action": "send_flow",
            "flow_id": "5854739484"
        }
    ]
}

​
Chuyển hội thoại cho nhân viên

Chuyển cuộc trò chuyện từ trạng thái chatbot tự động sang hàng chờ hỗ trợ trực tiếp của nhân viên: 
{
    "messages": [],
    "actions": [
        {
            "action": "transfer_conversation_to",
            "value": "human"
        }
    ]
}

​
Gán hội thoại cho Admin

Chỉ định một Admin cụ thể quản lý và trả lời cuộc hội thoại: 
{
    "messages": [],
    "actions": [
        {
            "action": "assign_conversation",
            "admin_id": "12345"
        }
    ]
}

​
Bỏ gán hội thoại

Gỡ bỏ Admin đang phụ trách và đưa cuộc trò chuyện trở lại danh sách hàng chờ chung: 
{
    "messages": [],
    "actions": [
        {
            "action": "unassign_conversation"
        }
    ]
}

​
Kết hợp nhiều hành động

Bạn có thể kết hợp chạy đồng thời nhiều hành động trong cùng một phản hồi: 
{
    "messages": [],
    "actions": [
        {
            "action": "set_field_value",
            "field_name": "phone",
            "value": "0912345678"
        },
        {
            "action": "send_flow",
            "flow_id": "5854739484"
        }
    ]
}

​
Sử dụng hành động làm Payload cho nút bấm và Lựa chọn nhanh

Do thuộc tính payload của nút bấm hoặc Quick Reply yêu cầu kiểu dữ liệu là chuỗi văn bản (string), bạn cần mã hóa (serialize) đối tượng chứa mảng actions thành một chuỗi JSON. Dưới đây là ví dụ cấu trúc nút bấm gọi hành động kích hoạt Flow sau khi nhấn: 
{
    "messages": [
        {
            "message": {
                "attachment": {
                    "payload": {
                        "buttons": [
                            {
                                "title": "Bắt đầu ngay",
                                "payload": "{\"actions\":[{\"action\":\"send_flow\",\"flow_id\":\"5854739484\"}]}",
                                "type": "postback"
                              }
                        ],
                        "template_type": "button",
                        "text": "Nhấn nút dưới đây để kích hoạt kịch bản tự động:"
                    },
                    "type": "template"
                },
                "quick_replies": []
            }            
        }
    ]
}

​
2 Phương thức triển khai Dynamic Content trên ChatbotX

Qua External API Request (Webhook)

Sử dụng trong kịch bản Flow Builder khi cần kết nối hệ thống CRM, ERP, Google Sheets hoặc Server riêng của doanh nghiệp.

Qua AI Agent (Rich Responses)

Cấu hình trực tiếp trong phần System Message (Prompt) của AI Agent để AI tự động xuất ra giao diện trực quan và thực thi lệnh.

​
Phương thức 1: Sử dụng trong Flow Builder (External API Request)

Trong trình chỉnh sửa kịch bản (Flow Builder), bạn sử dụng khối External API Request để gửi yêu cầu HTTP (GET hoặc POST) tới máy chủ của bạn. Máy chủ xử lý dữ liệu và trả về phản hồi dưới dạng JSON Dynamic Content.
1

Thêm hành động External API Request

Trong Flow Builder, chọn Actions > External API Request.
2

Cấu hình URL và Phương thức kết nối

Nhập đường dẫn Webhook của máy chủ (Endpoint URL), chọn phương thức (POST hoặc GET) và điền các tham số Header cần thiết (như API Key hoặc Authorization token).
3

Thiết lập phản hồi Dynamic Content

Tại mục cấu hình Response, chọn bật chế độ Dynamic Content. Máy chủ của bạn sẽ trả về chuỗi JSON chứa mảng messages và actions.
4

Kiểm tra và Xuất bản

Nhấn nút Test Request để kiểm tra dữ liệu trả về từ máy chủ, sau đó lưu kịch bản và tiến hành thử nghiệm thực tế.

​
Phương thức 2: Cấu hình cho AI Agent (Rich Responses)

Bạn dán quy tắc phản hồi JSON Dynamic Content vào ô System Message (Prompt) của AI Agent. Khi khách hàng trò chuyện, AI Agent tự động đóng vai trò như một máy chủ thông minh sinh ra chuỗi JSON Dynamic Content để ChatbotX hiển thị. Để xem hướng dẫn chi tiết và sao chép mẫu Prompt chuẩn thực tế, tham khảo bài viết Rich Responses. 
# Quy tắc đầu ra Dynamic Content

Bạn là một AI Agent phải luôn luôn trả về câu phản hồi dưới dạng JSON hợp lệ tuân theo cấu trúc Dynamic Content của ChatbotX:
{"messages": [...], "actions": [...]}

Quy tắc:
1. Root chỉ chứa 2 mảng: "messages" và "actions".
2. Khi tư vấn sản phẩm: Trả về tin nhắn Service Card (Generic Template) trong mảng "messages".
3. Khi khách chốt mua: Trả về tin nhắn xác nhận trong mảng "messages" và các lệnh add_tag, set_field_value, send_flow trong mảng "actions".
4. Chỉ trả về duy nhất chuỗi JSON hợp lệ, không kèm văn bản giải thích ngoài JSON.

​
Mẹo thực tiễn và giới hạn hệ thống

Khi sử dụng External Request để lấy dữ liệu từ máy chủ cá nhân, hệ thống ChatbotX tự động đính kèm thông tin ID người dùng trong HTTP Header dưới dạng X-USER-ID. Bạn có thể sử dụng Header này để xác định chính xác người dùng đang tương tác trên máy chủ của mình.
Lưu ý quan trọng về Custom Field: Để hệ thống lưu dữ liệu vào một Custom Field thông qua lệnh set_field_value, bạn bắt buộc phải tạo sẵn Custom Field đó trong cài đặt hệ thống ChatbotX trước. Nếu trường dữ liệu chưa được khởi tạo, lệnh Action sẽ bị bỏ qua.
Định dạng JSON hợp lệ: Đảm bảo chuỗi JSON trả về từ máy chủ hoặc AI Agent luôn là định dạng JSON hợp lệ (valid JSON). Nếu chuỗi JSON bị lỗi cú pháp (thiếu dấu ngoặc, sai dấu phẩy), hệ thống không thể hiển thị tin nhắn tới khách hàng.
Giới hạn cuộc gọi (Rate Limit): Tần suất giới hạn cuộc gọi mặc định đối với External Request là 100 requests trong mỗi 60 giây trên mỗi tài khoản bot.