Basis pengetahuan GetMyBot

Koleksi dan data

Simpan pendaftaran, pesanan, dan janji temu di GetMyBot. Buat tabel data, isi, lalu gunakan dalam reaksi.

Di halaman ini

Koleksi mirip sebuah tabel: satu baris mewakili satu pendaftaran, pesanan, atau janji temu. Bot dapat menambahkan baris dari jawaban pelanggan. Anda dapat melihat dan mengubahnya pada Data → Koleksi.

Misalnya, buat koleksi leads dengan kolom name, phone, dan topic untuk pendaftaran konsultasi. Setelah menanyakan nama, nomor telepon, dan topik, bot menyimpan jawabannya dalam satu baris. Reaksi berikutnya dapat mencari dan memakai data itu.

Apa itu koleksi

Kolom atau field menentukan jenis informasi, misalnya “Telepon” dan “Topik”. Catatan atau record adalah satu baris beserta nilainya. Daftar kolom dan jenis nilainya disebut skema. Secara teknis, catatan disimpan sebagai dokumen JSON. Jika Anda menambah kolom baru, catatan lama tidak perlu dibuat ulang.

Nama koleksi harus unik dalam satu bot. Nama tersebut dipakai dalam tindakan reaksi, misalnya leads, orders, atau scores.

Jenis kolom

Saat membuat koleksi, pilih jenis untuk setiap kolom:

JenisNilai yang disimpanContoh
textTeksNama, email, atau komentar
numberAngkaJumlah pembayaran, kuantitas, atau poin
boolYa atau tidak: true / falseApakah pesanan sudah dibayar
datetimeTanggal dan waktuWaktu janji temu
jsonObjek atau daftar dengan beberapa bagianRincian barang dalam pesanan

Jenis kolom menentukan cara nilainya diedit dan disimpan. Skema tetap fleksibel: jika suatu catatan memiliki kolom di luar skema, nilainya tetap tersimpan dan terlihat sebagai kolom tambahan.

Membuat koleksi

  1. Buka Data → Koleksi dan klik Tambah.
  2. Masukkan nama menggunakan huruf Latin tanpa spasi agar mudah dipakai dalam reaksi.
  3. Klik Field untuk menambah kolom, lalu pilih jenis masing-masing.
  4. Jika diperlukan, atur masa penyimpanan seperti dijelaskan di bawah, lalu simpan.

Melihat dan mengubah catatan

Pada kartu koleksi, klik ikon tabel untuk membuka jendela Data yang berisi catatannya:

  • Lihat: baris ditampilkan mulai dari yang terbaru, satu nilai per sel.
  • Tambah catatan: membuka formulir sesuai kolom koleksi. Kolom bool memakai tombol ya atau tidak, sedangkan json memakai tempat memasukkan JSON.
  • Edit dengan ikon pensil: mengubah baris yang sudah ada.
  • Hapus dengan ikon tempat sampah: menghapus baris.

Tindakan reaksi juga dapat menambah dan mengubah catatan secara otomatis. Data yang diubah manual dan oleh bot berada dalam koleksi yang sama.

Masa penyimpanan (retention)

Agar koleksi tidak terus bertambah tanpa batas, atur pembersihan otomatis:

  • Jumlah catatan maksimum: jika batas terlampaui, catatan paling lama dihapus.
  • Simpan paling lama (hari): catatan yang lebih tua daripada batas hari dihapus.

Misalnya, masa 30 hari cocok untuk log sementara. Pembersihan dilakukan secara berkala, jadi penghapusan tidak selalu tepat pada detik masa berlaku habis. Kedua batas dapat digunakan bersama. Jangan beri masa penyimpanan pada pesanan yang masih perlu ditangani.

Menggunakan data dalam reaksi

Tindakan berikut dapat membaca atau mengubah koleksi:

  • Buat catatan: menambah baris dengan nilai dari penggantian seperti {{user_id}} dan {{text}}. Kunci deduplikasi mencegah duplikat: jika tindakan dipanggil lagi dengan kunci yang sama, baris lama diperbarui. Misalnya, gunakan ID pengguna untuk menyimpan satu pendaftaran terbaru per orang.
  • Perbarui catatan: mengubah baris yang memenuhi syarat.
  • Cari catatan: membaca baris ke data sementara reaksi sebagai daftar.
  • Read collection page (record_page): membaca catatan per halaman, misalnya dua kartu sekaligus dengan tombol halaman berikutnya.
  • Aggregate whole collection (record_aggregate): menghitung jumlah dan total dari semua catatan yang memenuhi syarat dalam batas masa penyimpanan, bukan hanya halaman pertama.
  • Atomic collection transaction (collection_transaction): memeriksa syarat dan menyimpan beberapa perubahan bersama, misalnya menahan satu tempat dan membuat pendaftaran. Jika ada konflik, perubahan awal juga dibatalkan.
  • Hapus catatan: menghapus baris yang memenuhi syarat.
  • Perulangan pada daftar: memproses item dalam daftar satu per satu, misalnya memperbarui catatan, menghitung total, atau mengirim data ke layanan lain.

Dengan ini, bot dapat mencatat pelanggan, mengumpulkan pendaftaran, memberi poin, dan membuat laporan tanpa basis data terpisah.

Latihan tentang koleksi menjelaskan cara melanjutkan katalog, menghitung total seluruh pesanan yang cocok, dan memesan tempat terakhir. Halaman daftar yang sudah dimuat, halaman koleksi, dan perhitungan seluruh koleksi menghasilkan data yang berbeda untuk langkah berikutnya.

Jangan gunakan perulangan untuk mengirim siaran. Satu perulangan memproses paling banyak 500 item, dan satu peristiwa hanya boleh mengirim sampai 50 pesan. Jika perulangan mengirim satu pesan per item, hanya 50 pesan pertama yang terkirim; sisanya ditolak. Untuk mengirim pesan kepada orang dalam koleksi, buat segmen lalu kirim siaran, yang memiliki pengaturan kecepatan, jeda, dan catatan pengiriman. Baca Batas satu peristiwa.

Katalog: mencari, memilih, dan menampilkan kartu

Untuk mencoba alur ini, ikuti latihan mencari kelas. Latihan itu menunjukkan koleksi yang perlu disiapkan, urutan tindakan, serta cara memeriksa hasil kosong, beberapa hasil, dan ketukan tombol lama.

Untuk katalog, simpan data terpisah dari reaksi. Misalnya, koleksi products berisi name dan aliases; koleksi variants berisi product_id, name, dan card. Pada kolom variants.product_id, aktifkan Hubungan dengan koleksi lain, pilih products, kunci _record_id, dan kolom penanda name. Hubungan ini menjelaskan arti kolom, tetapi tidak mengubah atau menghapus catatan terkait secara otomatis.

  1. Pada reaksi untuk teks masuk, tambahkan Cari dalam koleksi (record_search). Pilih products, isi pencarian {{text}}, kolom utama name, kolom sinonim aliases, dan simpan hasil sebagai search. Sinonim dapat berupa teks atau daftar teks JSON. Pencarian tidak membedakan huruf besar-kecil; tanda baca dianggap sebagai spasi.
  2. Tambahkan Pilih langkah berikutnya (branch_result) dengan sumber search. Cabang pertama yang cocok dijalankan. Tangani Hasil belum lengkap terlebih dahulu dengan meminta pelanggan memperjelas pencarian. Setelah itu, tangani Tidak ditemukan, Kecocokan kurang tepat, Satu catatan, dan Beberapa catatan. Untuk kecocokan kurang tepat, minta konfirmasi. Hasil kosong dan satu catatan hanya pasti jika pencarian sudah lengkap.
  3. Untuk beberapa hasil, buka Tombol dari catatan yang ditemukan di editor pesan. Pilih sumber search, teks tombol dari name, dan reaksi berikutnya. Bantuan editor mengisi buttons_from.over = search.rows, templat teks, dan carry.selected_id = {{item._record_id}}. Pastikan name termasuk dalam hasil pencarian. Pengaturan tombol lanjutan tetap tersedia.
  4. Pada reaksi berikutnya, tambahkan Cari rekaman terkait (record_related): koleksi variants, kunci product_id, nilai {{ctx.selected_id}}, hasil variants. Untuk membaca produk yang dipilih, gunakan koleksi products dengan kunci _record_id. Jika hubungan memakai kunci bisnis lain, pilih kunci yang sama pada bantuan tombol dan tindakan pembacaan.
  5. Pilih cabang menurut hasilnya. Tampilkan satu varian sebagai kartu melalui {{ctx.variants.first.card}}, atau tampilkan beberapa varian sebagai tombol. Setiap tombol membawa ID catatan, lalu bot membaca data terbaru setelah tombol ditekan. Jangan menyimpan seluruh isi kartu atau kolom lain yang bisa berubah di carry.

Memahami hasil pembacaan

search.rows berisi daftar datar catatan, search.count jumlah baris yang dimuat, search.first catatan pertama, dan search.first.name satu kolom dari catatan itu. Setiap baris juga memiliki _record_id, _score, dan _match_type; ketiga nama ini sudah digunakan sistem. Jika hasil kosong, nilai catatan pertama dari pencarian sebelumnya dibersihkan.

search.total menghitung kecocokan di antara catatan yang sempat diperiksa. total_exact = false berarti belum semua catatan diperiksa; truncated = true berarti hasil dibatasi. Jangan menganggap hasil itu lengkap atau menjamin kecocokan terbaik dalam seluruh koleksi. Satu pencarian memeriksa paling banyak 10.000 catatan dan 16 MiB data; respons menunjukkan batas yang benar-benar tercapai. Secara bawaan, paling banyak 100 baris dikembalikan, dengan batas maksimum 10.000.

Memeriksa dan memahami hasil pencarian

Di editor pencarian, buka Uji pencarian dan masukkan teks atau ID contoh. Pemeriksaan ini hanya membaca data; reaksi berikutnya, pesan, dan tindakan lain tidak berjalan. Jika filter tambahan memakai penggantian nilai, masukkan nilai contoh terlebih dahulu. Hasil pemeriksaan menampilkan catatan, jenis kecocokan, jumlah catatan yang diperiksa, dan batasnya. Hasil lama disembunyikan jika proyek, koleksi, pengaturan, atau izin berubah.

Catatan pelaksanaan menunjukkan kolom pencarian, jenis kecocokan, jumlah catatan yang diperiksa dan dikembalikan, batas hasil, serta cabang yang dipilih. Diagram reaksi menampilkan semua syarat yang menuju reaksi yang sama. Saat meninjau pelaksanaan lama, penjelasan pencarian dapat dibuka dari peristiwanya jika Anda memiliki izin untuk melihat isinya.

Bantuan tombol secara bawaan membuat paling banyak 20 tombol. Anda dapat mengatur Jumlah tombol maksimum dari 1 sampai 100. Ini hanya batas jumlah, bukan pembagian halaman. Hasil kosong tidak membuat tombol. Untuk hasil yang lebih banyak, tambahkan cabang yang meminta pengguna memperjelas pencarian.

Pada tindakan Komputasi, bantuan Operasi pada daftar yang dimuat dapat membuat rumus untuk jumlah catatan, catatan pertama, jumlah nilai kolom, dan daftar teks. Rumus hanya memakai baris yang dimuat. Jika pencarian belum lengkap, hasilnya bukan total seluruh koleksi.

API dan MCP

Operasi yang sama tersedia melalui POST /api/bots/{botID}/collections/{name}/search dan /related, serta alat MCP search_records dan related_records dengan izin collections:read. Permintaan hanya dapat mengakses proyek dan wilayah saat ini. Uji melalui REST memakai nilai nyata; penggantian nilai dalam templat dilakukan oleh tindakan reaksi.

Mengolah hasil dan memperbarui dengan syarat

Anda dapat mengirim hasil koleksi ke list_transform untuk menyaring baris, mengurutkan, menghapus duplikat, atau mengambil satu halaman. list_aggregate menghitung total bernama dari baris yang dimuat, jika perlu menurut kelompok. Tindakan yang sama juga bekerja pada daftar biasa dari respons HTTP.

Agar dua reaksi yang berjalan bersamaan tidak mengubah keadaan yang sama dua kali, gunakan record_update_if: pilih ID catatan, nilai yang harus ada saat ini, dan nilai baru. Pemeriksaan dan perubahan dilakukan bersama untuk satu catatan. Hasil updated, conflict, atau not_found dapat ditangani dengan branch_value. Ini berbeda dari pembaruan tanpa syarat terhadap semua catatan yang cocok dengan filter.

Baca pengaturan, batas, dan contoh.

Latihan mengonfirmasi pendaftaran tanpa duplikat menunjukkan pemeriksaan status dan pemilik serta balasan terpisah untuk updated, conflict, dan not_found.

Membaca data dari Mini App

Telegram Mini App milik bot dapat membaca catatan koleksi. Aplikasi meminta data berdasarkan nama koleksi, filter, dan batas jumlah. Dengan begitu, pelanggan dapat melihat pesanan, riwayat, atau papan peringkat langsung di Telegram.

Saran

  • Beri kolom nama Latin yang singkat, seperti email, total, dan paid, agar mudah dipakai dalam templat reaksi.
  • Gunakan kunci deduplikasi agar pengulangan tindakan tidak membuat baris baru. Sifat ini juga disebut idempoten.
  • Atur masa penyimpanan untuk log dan data sementara yang tidak diperlukan lagi.
  • Gunakan jenis json jika bentuk nilainya tidak selalu sama.