Bộ sưu tập và dữ liệu

Bộ sưu tập là các bảng dữ liệu riêng của bot bạn. Chúng tiện lợi để lưu đơn đăng ký, đơn hàng, câu trả lời từ hội thoại, điểm trong trò chơi, lịch đặt chỗ — tất cả những gì bot thu thập từ người dùng hoặc nhận từ các tích hợp. Mục này nằm trong menu bên trái: Dữ liệu → Bộ sưu tập.

Bộ sưu tập là gì

Bộ sưu tập bao gồm trường (schema mô tả các cột) và bản ghi (hàng dữ liệu). Mỗi bản ghi là tập hợp giá trị theo các trường của bộ sưu tập; bên trong được lưu dưới dạng tài liệu JSON linh hoạt, nên bộ sưu tập dễ dàng xử lý việc thêm trường mới.

Tên bộ sưu tập là duy nhất trong phạm vi một bot và được dùng làm định danh trong các hành động phản ứng (ví dụ: leads, orders, scores).

Các loại trường

Khi tạo bộ sưu tập bạn xác định danh sách trường và kiểu dữ liệu cho mỗi trường:

text — chuỗi ký tự (tên, email, bình luận).
number — số (tổng tiền, số lượng, điểm).
bool — có/không (true / false).
datetime — ngày và giờ.
json — đối tượng lồng nhau hoặc mảng cho các giá trị phức tạp.

Kiểu dữ liệu ảnh hưởng đến cách trường được chỉnh sửa trong giao diện và cách giá trị được chuyển đổi khi lưu. Schema không cứng nhắc: nếu bản ghi có trường ngoài schema, nó vẫn được lưu và hiển thị trong cột riêng.

Tạo bộ sưu tập

Mở Dữ liệu → Bộ sưu tập và nhấn Thêm.
Nhập tên (bằng ký tự Latin, không có khoảng trắng — để dễ tham chiếu trong phản ứng).
Nhấn nút Trường để thêm cột cần thiết và chọn kiểu dữ liệu cho mỗi trường.
Nếu cần, đặt quy tắc lưu trữ (xem bên dưới) và lưu.

Bản ghi: xem và chỉnh sửa

Trên thẻ bộ sưu tập có nút với biểu tượng bảng — nó mở cửa sổ Dữ liệu với các bản ghi của bộ sưu tập đó:

Xem — tất cả hàng được hiển thị dạng danh sách, mỗi trường một ô, bắt đầu từ mới nhất.
Thêm bản ghi — mở form theo schema bộ sưu tập; mỗi trường được chỉnh sửa theo kiểu (công tắc cho bool, ô nhập JSON cho json, v.v.).
Sửa (bút chì) — chỉnh sửa hàng hiện có.
Xóa (thùng rác) — xóa hàng.

Bản ghi cũng được điền tự động — bởi các hành động phản ứng của bot (xem bên dưới). Chỉnh sửa thủ công và ghi tự động đều làm việc với cùng một bộ sưu tập.

Lưu trữ (retention)

Để bộ sưu tập không tăng trưởng vô hạn, hãy đặt quy tắc tự làm sạch:

Lưu tối đa số bản ghi — khi vượt giới hạn, các bản ghi cũ nhất bị xóa.
Lưu không quá (ngày) — các bản ghi cũ hơn khoảng thời gian đã chỉ định bị xóa.

Việc làm sạch được thực hiện định kỳ bởi tiến trình nền; các quy tắc có thể kết hợp với nhau.

Làm việc với dữ liệu từ phản ứng

Bộ sưu tập liên kết trực tiếp với trình xây dựng phản ứng. Trong các hành động phản ứng có sẵn:

Tạo bản ghi — thêm hàng; giá trị lấy từ template (ví dụ: {{user.id}}, {{message.text}}). Có thể đặt khóa deduplication để lần gọi lại sẽ cập nhật cùng hàng thay vì tạo bản trùng lặp.
Cập nhật bản ghi — thay đổi các hàng phù hợp với điều kiện.
Truy vấn bản ghi — đọc các hàng vào ngữ cảnh thực thi dưới dạng mảng để duyệt tiếp.
Xóa bản ghi — xóa các hàng theo điều kiện.
Vòng lặp (for-each) — duyệt qua mảng từ ngữ cảnh và thực hiện các hành động lồng nhau cho từng phần tử (ví dụ: gửi tin nhắn theo danh sách từ bộ sưu tập).

Nhờ vậy bot có thể quản lý CRM, tích lũy đơn đăng ký, cộng điểm và tạo báo cáo mà không cần cơ sở dữ liệu bên ngoài.

Truy cập từ Mini App

Bản ghi bộ sưu tập có thể được đọc từ Telegram Mini App của bot bạn: frontend yêu cầu dữ liệu bộ sưu tập theo tên với bộ lọc và giới hạn. Điều này cho phép hiển thị cho người dùng đơn hàng, lịch sử hoặc bảng xếp hạng ngay bên trong Telegram.

Mẹo

Đặt tên trường ngắn gọn dạng máy đọc được (email, total, paid) — tiện để chèn vào template phản ứng.
Với ghi idempotent (ví dụ: «một đơn đăng ký trên một người dùng») hãy dùng khóa deduplication.
Bật retention cho log và dữ liệu tạm để bộ sưu tập không phình to.
Kiểu json phù hợp khi cấu trúc giá trị chưa được xác định trước.