> ## 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.
# Minigame Gashapon
> Hướng dẫn chi tiết cách tạo và thiết lập minigame máy vặn trứng Gashapon trên ChatbotX: tùy biến núm xoay, hiệu ứng quả bóng rơi, cài đặt giải thưởng và kích hoạt kịch bản tự động.
**Gashapon** là trò chơi tương tác dạng Webview mô phỏng máy vặn trứng đồ chơi phong cách Nhật Bản. Khách hàng chạm vào núm xoay bắt đầu trên màn hình điện thoại, lồng kính chứa các quả bóng nhiều màu sắc sẽ rung lắc sôi động và một quả cầu may mắn sẽ rơi xuống khay mở ra phần thưởng bí mật.
Cơ chế "mở hộp quà bí mật" (blind box) của Gashapon kích thích mạnh mẽ trí tò mò của khách hàng, giúp doanh nghiệp bùng nổ tỷ lệ tương tác tin nhắn, thu hút khách hàng tiềm năng và khuyến khích chia sẻ lan truyền qua mạng xã hội.
Mô phỏng chân thực chuyển động rung lắc của các quả cầu trong lồng kính và hiệu ứng mở trứng rực rỡ khi trúng thưởng.
Tự động cộng thêm lượt vặn trứng khi liên hệ giới thiệu bạn bè tham gia và kích hoạt khối kịch bản chào mừng người được mời.
Phân loại tự động liên hệ mở link, người tham gia chơi và bạn bè mới, đồng thời lưu tên giải thưởng trúng vào Thuộc tính tùy chỉnh.
Kiểm soát tổng xác suất trúng 100%, giới hạn số lượng từng giải thưởng và đặt lịch làm mới lượt quay định kỳ theo ngày.
## Truy cập tính năng Gamification
Để bắt đầu, từ menu thanh bên trái của ChatbotX, chọn **Tools** và nhấn vào thẻ **Gamification**:
## Bảng quản lý danh sách trò chơi
Trang tổng quan Gamification hiển thị danh sách toàn bộ các trò chơi đã tạo cùng các chỉ số đo lường hiệu quả thời gian thực:
### Ý nghĩa các chỉ số đo lường
| Chỉ số | Ý nghĩa và cách tính |
| - | - |
| **Name** | Tên của minigame hiển thị trên hệ thống và trên trang Webview của khách hàng. |
| **Games played** | Tổng số lượt quay thưởng đã được thực hiện. Ví dụ: Nếu 1 liên hệ quay 3 lần, hệ thống sẽ ghi nhận 3 lượt. |
| **Participants** | Tổng số người tham gia thực tế (Unique Users). Ví dụ: Nếu 1 liên hệ quay 3 lần, hệ thống chỉ tính là 1 người tham gia. |
| **Winners** | Tổng số lượt quay trúng thưởng được ghi nhận trong suốt chương trình. |
| **Referrals** | Tổng số lượng bạn bè mới tham gia thông qua liên kết chia sẻ của người chơi. |
| **Status** | Công tắc bật hoặc tắt trạng thái hoạt động của trò chơi. |
| **Created At** | Ngày giờ khởi tạo minigame. |
### Menu thao tác
Nhấn vào biểu tượng dấu ba chấm (`...`) ở cột cuối cùng của từng trò chơi để thực hiện:
* **Edit:** Mở màn hình cấu hình chi tiết trò chơi.
* **History:** Xem báo cáo danh sách người tham gia và số lượt đã quay.
* **Delete:** Xóa trò chơi khỏi hệ thống.
## Tạo mới Minigame Gashapon
Tại trang Gamification, nhấn nút **+ Create Minigame** ở góc trên bên phải để mở hộp thoại lựa chọn định dạng trò chơi:
Nhấn chọn thẻ **Gashapon** để bắt đầu khởi tạo trò chơi. Màn hình cấu hình minigame Gashapon sẽ hiển thị với 2 tab chính ở thanh điều hướng trên cùng: **Edit** (Cấu hình trò chơi) và **History** (Báo cáo lịch sử người chơi):
## Thiết lập Cài đặt chung
Khu vực **General Setting** nằm ở cột bên trái, dùng để thiết lập thông tin hiển thị cơ bản và hệ thống gắn Thẻ tự động:
* **Name:** Tên gọi của minigame Gashapon. Nút gạt **Visible** bên cạnh cho phép bạn bật hoặc tắt tính năng hiển thị tên game ở đầu trang Webview trên điện thoại.
* **Played At:** Khoảng thời gian trò chơi diễn ra (ngày giờ bắt đầu và kết thúc). Ngoài thời gian này, liên hệ mở liên kết sẽ không thể thực hiện quay thưởng.
* **Rules Description (optional):** Mô tả thể lệ và luật chơi (ví dụ: *Vặn trứng may mắn để rinh quà khủng. Mỗi khách hàng nhận 1 lượt miễn phí mỗi ngày*). Phần văn bản này sẽ hiển thị trực tiếp ở chân trang minigame trên điện thoại.
* **Tag contacts who open the game link (optional):** Chọn Thẻ tự động gắn cho những liên hệ nhấp mở liên kết máy Gashapon (dù chưa bấm vặn). Giúp bạn lọc danh sách khách hàng quan tâm để remarketing gửi tin nhắc nhở.
* **Tag players (optional):** Chọn Thẻ tự động gắn cho những liên hệ đã bấm nút vặn trứng.
* **Tag new friends (optional):** Chọn Thẻ tự động gắn cho những liên hệ mới lần đầu biết đến bot thông qua liên kết giới thiệu của người chơi khác.
## Tùy biến giao diện
Khu vực **Appearance** cho phép bạn tùy chỉnh bảng màu máy vặn trứng và tải lên hình ảnh đồ họa riêng:
### Bảng màu máy vặn trứng
* **Background Color:** Màu nền bao quanh trang trò chơi (mã màu Hex).
* **Machine Color:** Màu sắc chủ đạo của thân máy vặn trứng Gashapon.
* **Rule Text Color:** Màu chữ hiển thị của phần mô tả luật chơi ở chân trang.
### Quy chuẩn kích thước hình ảnh tải lên
* **Background Image:** Hình nền chính của trang game. Chiều rộng khuyến nghị là **1024px**. Chiều cao sẽ co giãn tự động theo nội dung.
* **Prize Description Image (Optional):** Ảnh banner giới thiệu cơ cấu giải thưởng đặt ở phần đầu game. Chiều rộng khuyến nghị là **750px**. Bạn có thể tải tệp lên (**Upload File**) hoặc dán liên kết ảnh trực tiếp (**Insert Link**).
* **Start Button Image:** Ảnh núm vặn xoay khởi động máy Gashapon (thay thế núm xoay mặc định). Kích thước khuyến nghị chuẩn là **253 x 300px**.
Khi bạn thay đổi màu sắc hoặc tải ảnh núm vặn mới lên, khung mô phỏng di động (**Live Mobile Preview**) ở cột bên phải sẽ cập nhật trực quan ngay lập tức để bạn kiểm tra bố cục trước khi nhấn lưu. Phía dưới cùng của phần luật chơi luôn được hệ thống giữ lại khoảng 60px vùng trống để nội dung không bị che khuất trên các màn hình điện thoại có tai thỏ hoặc thanh điều hướng ảo.
## Cài đặt người chơi và cơ chế lan truyền
Khu vực **Player Settings** nằm ở cột giữa, quy định số lượt chơi, cơ chế mời bạn bè và quy tắc làm mới lượt quay:
### Số lượt quay mặc định
* **Number of lucky draw chances per person:** Số lượt vặn trứng ban đầu cấp cho mỗi liên hệ khi tham gia trò chơi (mặc định là 1 lượt).
### Cơ chế chia sẻ nhận thêm lượt
* **Max bonus draws from referrals (optional):** Số lượt quay thưởng tối đa mà một người chơi có thể nhận được từ việc giới thiệu bạn bè.
* Khi một người bạn mới bấm vào link mời của người chơi và gửi tin nhắn vào bot, người giới thiệu sẽ được cộng thêm 1 lượt quay (tối đa bằng giới hạn bạn đặt ở đây).
* Đặt giá trị bằng **0** nếu bạn muốn tắt hoàn toàn cơ chế thưởng thêm lượt khi giới thiệu.
* **Sharing node (optional):** Chọn bước cụ thể trong Kịch bản (**Node**) sẽ tự động kích hoạt khi người bạn mới mở liên kết chia sẻ. Nếu để trống ô này, nút chia sẻ (**Share button**) trên màn hình của người chơi sẽ tự động ẩn đi.
Khi người chơi đã sử dụng hết số lượt quay mặc định, màn hình Webview sẽ tự động hiển thị thông báo *You are out of draws for this minigame* kèm nút **Share with friends**:
Khi người chơi nhấn vào nút **Share with friends**, thiết bị sẽ mở bảng chia sẻ liên kết giới thiệu cá nhân hóa. Người bạn khi nhấp vào liên kết và nhắn tin vào bot sẽ kích hoạt bước kịch bản bạn đã chọn ở mục **Sharing node**, đồng thời hệ thống tự động cộng thêm lượt quay thưởng cho người giới thiệu ban đầu.
### Quy tắc làm mới lượt quay
* **Do not reset the number of draws:** Không làm mới lượt quay. Người chơi dùng hết số lượt ban đầu (cộng lượt thưởng nếu có) sẽ không được chơi thêm.
* **Reset the number of draws every:** Tự động khôi phục lại số lượt quay mặc định sau mỗi khoảng thời gian bạn chọn (ví dụ: đặt lại sau mỗi 1 ngày vào lúc 00:00).
**Lưu ý quan trọng về chu kỳ làm mới:** Khi chu kỳ làm mới lượt chơi diễn ra (ví dụ lúc 00:00 hằng ngày), **toàn bộ số lượt quay thưởng kiếm được từ việc mời bạn bè mà người chơi chưa sử dụng hết cũng sẽ bị làm mới (reset)** theo chu kỳ này. Hãy lưu ý điều này trong phần mô tả thể lệ luật chơi để khuyến khích khách hàng sử dụng hết lượt quay trong ngày.
## Cài đặt giải thưởng và xác suất trúng
Khu vực **Prize Settings** giúp bạn quản lý danh mục quà tặng trong các quả trứng, xác suất trúng và lưu dữ liệu người trúng:
### Chỉ số kiểm soát xác suất
Hệ thống tự động tính toán và hiển thị các chỉ số xác suất ngay đầu mục:
* **Sum of all probabilities:** Tổng xác suất của tất cả các phần tử (bắt buộc phải bằng **100%**).
* **Win probability:** Tổng tỷ lệ trúng của tất cả các giải thưởng cộng lại.
* **Lose probability:** Tỷ lệ rơi vào ô không trúng thưởng (**Non-winning**).
### Lưu tên giải thưởng vào Thuộc tính
* **Save prize name to Custom Field (optional):** Chọn một Thuộc tính tùy chỉnh (Custom Field) dạng Text (ví dụ: *Prize Name*). Khi người chơi vặn trúng bất kỳ giải nào, tên của giải thưởng đó sẽ được tự động ghi vào Thuộc tính của liên hệ để phục vụ việc gửi tin nhắn hoặc xuất báo cáo.
### Thêm và chỉnh sửa phần thưởng
Trong danh sách giải thưởng, bạn có thể chỉnh sửa trực tiếp xác suất (%) của từng giải, bấm vào biểu tượng thùng rác để xóa, hoặc nhấn vào biểu tượng cây bút để mở hộp thoại **Edit Prize**:
Trong hộp thoại **Edit Prize**, bạn thiết lập:
* **Prize Name:** Tên phần quà chứa trong quả trứng (ví dụ: *Mô hình linh vật*, *Voucher 100K*, *Túi canvas thời trang*).
* **Image:** Tải tệp lên hoặc chèn liên kết hình ảnh quà tặng hiển thị khi quả trứng mở ra.
* **Prize Quantity (optional):** Giới hạn số lượng quà tặng thực tế phát ra. Mỗi khi có người chơi vặn trúng, số lượng này sẽ tự động giảm đi 1. Khi số lượng về 0, giải thưởng này sẽ không thể trúng thêm nữa. Nếu để trống, số lượng giải thưởng là không giới hạn.
Nhấn **+ New Prize** để thêm các phần quà mới, hoặc nhấn cây bút tại dòng **Non-winning** để điều chỉnh tỷ lệ và nội dung quả trứng rỗng (chúc may mắn lần sau).
**Cơ chế bảo toàn khi hết kho quà:** Khi một giải thưởng có giới hạn số lượng đã được trao hết (số lượng còn lại bằng 0), hệ thống sẽ **tự động chuyển các lượt quay rơi vào giải này sau đó thành lượt quay không trúng thưởng (Non-winning)**. Cơ chế này đảm bảo bạn không bao giờ bị vượt ngân sách quà tặng thực tế mà tổng xác suất của toàn bộ trò chơi vẫn luôn duy trì ở mức 100%.
## Cài đặt thông báo kết quả và trả thưởng tự động
Sau khi quả trứng rơi xuống và mở ra, màn hình Webview sẽ hiển thị thông báo kết quả. Bạn có thể nhấn vào biểu tượng cây bút tại mục **Winning Message Settings** và **Non-winning Message Settings** để thiết lập:
### Thông báo trúng thưởng
* **Title (optional):** Tiêu đề chúc mừng (ví dụ: *Congratulations*).
* **Description (optional):** Nội dung mô tả chi tiết quà tặng. Bạn có thể chèn mã `{{prize_name}}` vào tiêu đề hoặc mô tả để hệ thống tự động điền tên giải thưởng mà khách vừa trúng.
* **Accept Button Text (optional):** Tên nút bấm nhận thưởng hiển thị trên Webview (ví dụ: *Redeem Now* hoặc *Nhận quà ngay*).
* **Send message to winner who received the prize (optional):** Bật công tắc này nếu bạn muốn bot tự động gửi tin nhắn cho người chơi ngay khi họ trúng giải.
* **Message type:** Chọn 1 trong 3 hình thức gửi:
* **Text:** Gửi tin nhắn văn bản thông thường.
* **Flow:** Kích hoạt một Kịch bản hoàn chỉnh (chọn theo **Flow ID**) để gửi mã coupon, yêu cầu khách điền địa chỉ nhận quà.
* **Node:** Điều hướng trực tiếp đến một bước cụ thể trong kịch bản.
### Thông báo không trúng thưởng
* **Title (optional):** Tiêu đề thông báo (ví dụ: *Tiếc quá, quả trứng này rỗng rồi!*).
* **Description (optional):** Lời nhắn an ủi và hướng dẫn chia sẻ bạn bè để nhận thêm lượt vặn trứng mới.
* **Send a message when the player doesn't win (optional):** Bật công tắc nếu bạn muốn bot gửi tin nhắn động viên người chơi thử lại hoặc gửi kèm mã ưu đãi an ủi.
## Theo dõi báo cáo lịch sử người chơi
Chuyển sang tab **History** ở thanh điều hướng trên cùng để xem danh sách chi tiết các liên hệ đã tương tác với minigame Gashapon:
Bảng theo dõi bao gồm các trường thông tin quan trọng:
* **Name:** Ảnh đại diện và tên của liên hệ trên nền tảng nhắn tin.
* **Plays:** Tổng số lượt vặn trứng mà liên hệ này đã thực hiện.
* **Remaining draws:** Số lượt vặn trứng còn lại chưa sử dụng.
* **Referrals:** Số lượng bạn bè mới đã tham gia qua liên kết mời của liên hệ này.
* **First opened:** Ngày giờ lần đầu tiên liên hệ bấm mở trò chơi.
* **Last played:** Ngày giờ của lượt vặn trứng gần nhất.
* **Actions (⋮):** Các thao tác quản lý nhanh đối với từng người chơi.
Bạn có thể sử dụng ô **Search name...** để tìm kiếm người chơi theo tên hoặc điều chỉnh số dòng hiển thị trên mỗi trang (**Rows per page**).
## Tích hợp Minigame Gashapon vào Kịch bản Chatbot
Ở góc dưới cùng của trang cấu hình, hệ thống cung cấp sẵn đường dẫn **Public URL**:
```text theme={null}
https://app.chatconnectx.com/minigames?minigameId=XXXXXX
```
Nhấn vào biểu tượng sao chép để lấy đường dẫn này. Bạn có thể dán liên kết vào nút bấm dạng **Open Website** trong Kịch bản (Flows), chiến dịch gửi tin nhắn hàng loạt (Broadcasts), chuỗi tin nhắn chăm sóc (Sequences) hoặc các bài viết quảng cáo để dẫn khách hàng vào vặn trứng.
Dưới đây là 3 kịch bản ứng dụng thực chiến phổ biến nhất:
### Kịch bản 1: Thu hút khách mới qua quảng cáo
Tạo một Kịch bản (Flow) tự động gửi tin nhắn chào mừng ngay khi khách hàng nhắn tin từ bài quảng cáo Facebook hoặc Instagram. Gắn nút bấm **Open Website** trỏ đến đường dẫn minigame Gashapon để tặng khách lượt vặn trứng may mắn đầu tiên, gia tăng tỷ lệ phản hồi tin nhắn lên gấp 2-3 lần.
### Kịch bản 2: Trả thưởng tự động bằng Mã giảm giá
Trong phần **Winning Message Settings**, bạn chọn hình thức gửi tin nhắn là **Flow**. Thiết lập Kịch bản này chứa Action **Set up Coupon** thuộc tính năng [Mã giảm giá (Coupons)](/docs/vi/tools/coupons). Khi khách vặn trúng giải, bot sẽ tự động phát một mã ưu đãi duy nhất kèm hạn sử dụng trực tiếp trong hộp thoại chat để khách tiến hành mua hàng ngay.
### Kịch bản 3: Kích thích khách hàng cũ quay lại
Tận dụng tính năng đặt lại lượt quay mỗi ngày (**Reset every 1 day**). Kết hợp với tính năng [Gửi tin nhắn hàng loạt (Broadcasts)](/docs/vi/remarketing/omnichannel-broadcasts), bạn gửi tin nhắn thông báo lượt vặn trứng ngày mới cho tệp liên hệ cũ để duy trì sự hiện diện thương hiệu và tăng trưởng doanh số đều đặn.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.