Collections and Data

Collections are your bot's own data tables. They are a convenient place to store leads, orders, dialog responses, game scores, class registrations: anything the bot gathers from users or receives from integrations. Find them in the left menu under Data → Collections.

What is a collection

A collection consists of fields (a schema describing the columns) and records (rows of data). Each record is a set of values for the collection's fields; internally it is stored as a flexible JSON document, so the collection handles the addition of new fields without issue.

A collection name is unique within a single bot and is used as an identifier in reaction actions (e.g., leads, orders, scores).

Field types

When creating a collection you define a list of fields and the type of each:

• text: a string (name, email, comment).
• number: a number (amount, quantity, score).
• bool: yes/no (true / false).
• datetime: date and time.
• json: a nested object or array for complex values.

The type affects how the field is edited in the interface and how the value is coerced on save. The schema is not strict: if a record contains a field not in the schema, it will be saved and displayed as a separate column.

Creating a collection

1. Open Data → Collections and click Add.
2. Provide a name (Latin characters, no spaces: easier to reference in reactions).
3. Use the Field button to add the columns you need and choose the type for each.
4. If needed, configure retention rules (see below) and save.

Records: viewing and editing

The collection card has a table-icon button that opens the Data window with the collection's records:

• View: all rows are listed, one cell per field, newest first.
• Add record: opens a form based on the collection schema; each field is edited according to its type (toggle for bool, JSON input for json, etc.).
• Edit (pencil): modifies an existing row.
• Delete (trash): removes a row.

Records are also populated automatically by the bot's reaction actions (see below). Manual editing and auto-write work against the same collection.

Retention

To prevent a collection from growing indefinitely, configure auto-cleanup rules:

• Maximum records: when the limit is exceeded, the oldest records are deleted.
• Retain for (days): records older than the specified period are deleted.

Cleanup is performed periodically by a background process; rules can be combined.

Working with data from reactions

Collections are directly connected to the reaction builder. The following actions are available in a reaction:

• Create record: adds a row; values are taken from templates (e.g., {{user.id}}, {{message.text}}). You can set a deduplication key so that a repeated call updates the same row instead of creating a duplicate.
• Update records: modifies rows matching a condition.
• Query records: reads rows into the execution context as an array for further iteration.
• Delete records: removes rows matching a condition.
• Loop (for-each): iterates over an array in the context and runs nested actions for each element: updating each row, totalling a figure, pushing each record to an external service.

This lets the bot act as a CRM, accumulate leads, award points, and build reports without an external database.

A loop is not a sending tool. One pass takes at most 500 elements, while the whole event may send at most 50 messages: a loop with a message send inside delivers the first 50 and is refused on the rest. To write to the people in a collection, build a segment from it and run a broadcast: that is where pacing, pausing and delivery accounting live. More on the boundaries in Actions → The budget of one event.

Access from Mini App

Collection records can be read from your bot's Telegram Mini App: the frontend requests collection data by name with filters and a limit. This allows you to display a user's orders, history, or leaderboard directly inside Telegram.

Tips

• Give fields short, machine-friendly names (email, total, paid): they are easier to use in reaction templates.
• For idempotent writes (e.g., "one lead per user"), use a deduplication key.
• Enable retention for logs and temporary data to keep the collection from growing unbounded.
• The json type is suitable when the value structure is not known in advance.