Koleksi dan data

Koleksi adalah tabel data bawaan bot Anda. Di sana mudah untuk menyimpan aplikasi, pesanan, jawaban dari dialog, poin dalam permainan, pendaftaran kelas — semua yang dikumpulkan bot dari pengguna atau diterima dari integrasi. Bagian ini ada di menu kiri: Data → Koleksi.

Apa itu koleksi

Koleksi terdiri dari field (skema yang mendeskripsikan kolom) dan record (baris dengan data). Setiap record adalah sekumpulan nilai berdasarkan field koleksi; secara internal disimpan sebagai dokumen JSON yang fleksibel, sehingga koleksi tidak masalah dengan penambahan field baru.

Nama koleksi unik dalam satu bot dan digunakan sebagai identifier dalam aksi reaksi (misalnya, leads, orders, scores).

Tipe field

Saat membuat koleksi, Anda menentukan daftar field dan tipe masing-masing:

  • text — string (nama, email, komentar).
  • number — angka (jumlah, kuantitas, poin).
  • bool — ya/tidak (true / false).
  • datetime — tanggal dan waktu.
  • json — objek bersarang atau array untuk nilai kompleks.

Tipe memengaruhi cara field diedit di antarmuka dan bagaimana nilai dikonversi saat disimpan. Skema tidak kaku: jika sebuah record memiliki field di luar skema, field tersebut akan disimpan dan ditampilkan sebagai kolom terpisah.

Membuat koleksi

  1. Buka Data → Koleksi dan klik Tambah.
  2. Masukkan nama (dalam huruf Latin, tanpa spasi — lebih mudah direferensikan dalam reaksi).
  3. Dengan tombol Field tambahkan kolom yang diperlukan dan pilih tipe masing-masing.
  4. Jika perlu, atur aturan penyimpanan (lihat di bawah) dan simpan.

Record: tampilan dan pengeditan

Di kartu koleksi ada tombol dengan ikon tabel — membuka jendela Data dengan record koleksi ini:

  • Tampilan — semua baris ditampilkan sebagai daftar, per field per sel, mulai dari yang terbaru.
  • Tambah record — membuka form berdasarkan skema koleksi; setiap field diedit sesuai tipenya (toggle untuk bool, field input JSON untuk json, dll.).
  • Edit (pensil) — mengedit baris yang ada.
  • Hapus (tempat sampah) — menghapus baris.

Record juga diisi secara otomatis oleh aksi reaksi bot (lihat di bawah). Pengeditan manual dan penulisan otomatis bekerja pada koleksi yang sama.

Penyimpanan (retention)

Agar koleksi tidak terus berkembang tanpa batas, atur aturan pembersihan otomatis:

  • Simpan maksimal record — jika melebihi batas, record paling lama akan dihapus.
  • Simpan tidak lebih dari (hari) — record yang lebih lama dari periode yang ditentukan akan dihapus.

Pembersihan dilakukan oleh proses latar belakang secara berkala; aturan dapat dikombinasikan.

Bekerja dengan data dari reaksi

Koleksi terhubung langsung dengan builder reaksi. Dalam aksi reaksi tersedia:

  • Buat record — menambahkan baris; nilai diambil dari template (misalnya, {{user.id}}, {{message.text}}). Anda dapat mengatur kunci deduplikasi agar pemanggilan berulang memperbarui baris yang sama, bukan membuat duplikat.
  • Perbarui record — mengubah baris yang memenuhi kondisi.
  • Ambil record — membaca baris ke dalam konteks eksekusi sebagai array untuk diiterasi selanjutnya.
  • Hapus record — menghapus baris berdasarkan kondisi.
  • Loop (for-each) — mengiterasi array dari konteks dan menjalankan aksi bersarang untuk setiap elemen (misalnya, mengirim pesan ke daftar dari koleksi).

Dengan cara ini bot dapat mengelola CRM, mengumpulkan aplikasi, memberikan poin, dan membuat laporan tanpa basis data eksternal.

Akses dari Mini App

Record koleksi dapat dibaca dari Telegram Mini App bot Anda: frontend meminta data koleksi berdasarkan nama dengan filter dan limit. Ini memungkinkan Anda menampilkan pesanan, riwayat, atau papan skor pengguna langsung di dalam Telegram.

Tips

  • Berikan field nama mesin yang pendek (email, total, paid) — lebih mudah digunakan dalam template reaksi.
  • Untuk penulisan idempoten (misalnya, "satu aplikasi per pengguna") gunakan kunci deduplikasi.
  • Aktifkan retention untuk log dan data sementara agar koleksi tidak membesar.
  • Tipe json cocok ketika struktur nilai tidak ditentukan terlebih dahulu.