مجموعهها و دادهها
مجموعهها جداول داده اختصاصی بات شما هستند. در آنها میتوانید درخواستها، سفارشها، پاسخهای مکالمات، امتیازها، ثبتنامها — هر چیزی که بات از کاربران جمعآوری میکند یا از یکپارچهسازیها دریافت میکند — را ذخیره کنید. این بخش در منوی سمت چپ قرار دارد: دادهها → مجموعهها.
مجموعه چیست
یک مجموعه از فیلدها (طرحوارهای که ستونها را توصیف میکند) و رکوردها (ردیفهایی با داده) تشکیل شده است. هر رکورد مجموعهای از مقادیر بر اساس فیلدهای مجموعه است؛ در داخل به صورت یک سند JSON انعطافپذیر ذخیره میشود، بنابراین اضافه شدن فیلدهای جدید مشکلی ایجاد نمیکند.
نام مجموعه در محدوده یک بات منحصربهفرد است و به عنوان شناسه در اقدامات واکنشها استفاده میشود (مثلاً leads، orders، scores).
انواع فیلد
هنگام ایجاد مجموعه، فهرست فیلدها و نوع هر کدام را مشخص میکنید:
- text — رشته (نام، ایمیل، نظر).
- number — عدد (مبلغ، تعداد، امتیاز).
- bool — بله/خیر (
true/false). - datetime — تاریخ و زمان.
- json — شیء تو در تو یا آرایه برای مقادیر پیچیده.
نوع بر نحوه ویرایش فیلد در رابط و نحوه تبدیل مقدار هنگام ذخیرهسازی تأثیر میگذارد. طرحواره سختگیرانه نیست: اگر رکوردی فیلدی خارج از طرحواره داشته باشد، ذخیره شده و در یک ستون جداگانه نمایش داده میشود.
ایجاد مجموعه
- دادهها → مجموعهها را باز کنید و روی افزودن کلیک کنید.
- نام را مشخص کنید (به حروف لاتین، بدون فاصله — این ارجاع به آن در واکنشها را آسانتر میکند).
- با دکمه فیلد ستونهای لازم را اضافه و نوع هر کدام را انتخاب کنید.
- در صورت نیاز قوانین نگهداری را تنظیم کنید (ببینید پایین) و ذخیره کنید.
رکوردها: مشاهده و ویرایش
در کارت مجموعه یک دکمه با آیکون جدول وجود دارد — که پنجره دادهها با رکوردهای این مجموعه را باز میکند:
- مشاهده — همه ردیفها به صورت فهرست نمایش داده میشوند، یک فیلد در هر سلول، از جدیدترین شروع میشود.
- افزودن رکورد — فرمی بر اساس طرحواره مجموعه باز میکند؛ هر فیلد بر اساس نوع خود ویرایش میشود (کلید تبدیل برای
bool، فیلد ورودی JSON برایjsonو غیره). - ویرایش (مداد) — ردیف موجود را ویرایش میکند.
- حذف (سطل) — ردیف را حذف میکند.
رکوردها همچنین به صورت خودکار از طریق اقدامات واکنشهای بات پر میشوند (ببینید پایین). ویرایش دستی و ثبت خودکار با یک مجموعه یکسان کار میکنند.
نگهداری (retention)
برای جلوگیری از رشد بینهایت مجموعه، قوانین پاکسازی خودکار را تنظیم کنید:
- نگهداری حداکثر رکوردها — هنگام تجاوز از محدودیت، قدیمیترین رکوردها حذف میشوند.
- نگهداری نه بیشتر از (روز) — رکوردهای قدیمیتر از مدت مشخصشده حذف میشوند.
پاکسازی به صورت دورهای توسط یک فرآیند پسزمینه انجام میشود؛ قوانین را میتوان ترکیب کرد.
کار با دادهها از واکنشها
مجموعهها مستقیماً با سازنده واکنشها مرتبط هستند. در اقدامات واکنش در دسترس است:
- ایجاد رکورد — یک ردیف اضافه میکند؛ مقادیر از قالبها گرفته میشوند (مثلاً
{{user.id}}،{{message.text}}). میتوانید کلید عدم تکرار تنظیم کنید تا فراخوانی مجدد همان ردیف را بهروز کند نه اینکه تکراری ایجاد کند. - بهروزرسانی رکوردها — ردیفهایی که با شرط مطابقت دارند را تغییر میدهد.
- درخواست رکوردها — ردیفها را به عنوان آرایه به زمینه اجرا میخواند تا بعداً روی آنها پیمایش شود.
- حذف رکوردها — ردیفها را بر اساس شرط حذف میکند.
- حلقه (for-each) — روی آرایهای از زمینه پیمایش میکند و اقدامات تو در تو را برای هر عنصر اجرا میکند (مثلاً ارسال پیام بر اساس فهرستی از مجموعه).
به این ترتیب بات میتواند CRM نگهداری کند، درخواستها جمع کند، امتیاز اضافه کند و گزارشها بسازد بدون پایگاه داده خارجی.
دسترسی از Mini App
رکوردهای مجموعه را میتوان از Telegram Mini App بات خود خواند: فرانتاند دادههای مجموعه را بر اساس نام با فیلترها و محدودیت درخواست میکند. این امکان را میدهد که سفارشها، تاریخچه یا جدول رتبهبندی کاربر را مستقیماً در داخل Telegram نمایش دهید.
نکات
- به فیلدها نامهای ماشینی کوتاه بدهید (
email،total،paid) — درج آنها در قالبهای واکنش راحتتر است. - برای ثبت ایمن (مثلاً «یک درخواست در ازای هر کاربر») از کلید عدم تکرار استفاده کنید.
- برای لاگها و دادههای موقت retention را فعال کنید تا مجموعه رشد نکند.
- نوع
jsonزمانی مناسب است که ساختار مقدار از قبل ثابت نباشد.