Database

The Database block allows you to read and modify data directly from the scenario: user profiles, products, files, orders, payments, subscriptions, and other objects.

Each block works with a single data source. Within the source, you add one or more actions that are executed sequentially.

Once a source is selected, it cannot be changed as long as there are actions added to the block. You must delete all actions first.

Available Sources

Source	What it stores
User	Profile, balance, credits, tags, and other bot participant fields
Product	Product listings from the store: name, price, quantity, statistics
Files	Media files from the bot's library
Orders	Orders from the built-in store
User Config	Custom settings linked to the bot participant
User Records	Logs, conversation history, AI token counters
User Statistics	Custom data by day and type (key-value pairs)
Payments	Records of payments made via the bot
Subscriptions	Records of recurring (periodic) subscriptions
User Schedules	Personal broadcast schedules: type + time + days + time zone

User

Reading and modifying profile data for any bot participant.

Available Actions

Action	Description
Get User	Loads participant data into a variable (default: "user")
Change First Name	Sets a new first name
Change Last Name	Sets a last name
Change Patronymic	Sets a patronymic
Change Language	Two-letter code: "ru", "en", etc.
Change Status	Active or Blocked
Change phone	Sets the phone number
Change email	Sets the email address
Change age	Integer from 1 to 200
Change date of birth	Date in "YYYY-MM-DD" format
Change time of birth	Arbitrary string
Change place of birth	Arbitrary string
Change city	Sets the city
Change address	Sets the delivery address
Change location	Coordinates or text-based location
Change bio	Arbitrary text
Change interests	Arbitrary text
Change device	Device information
Set tag	Arbitrary tag string (e.g., "vip", "partner")
Block	Blocks the user in the bot
Unblock	Removes the block
Add credits	Increases the credit count (integer)
Deduct credits	Decreases the credit count (integer)
Add bonuses	Increases the bonus amount (decimal number)
Deduct bonuses	Decreases the bonus amount; becomes 0 if deduction exceeds current value
Increase available balance	Adds to the balance (decimal number)
Decrease available balance	Subtracts from the balance; becomes 0 if deduction exceeds balance
Increase earnings	Adds to the "earned" field (decimal number)
Decrease earnings	Subtracts from the "earned" field; becomes 0 if deduction exceeds earnings
Increase referral earnings	Adds to referral earnings
Decrease referral earnings	Subtracts from referral earnings; if the amount is exceeded, it becomes 0
Update payment due date	Date in "YYYY-MM-DD HH:MM" format or Unix timestamp
Update payment time	Date of the last payment

User properties

After the "Get user" action, the variable ("user") contains:

Variable	Description
"{{user.id}}"	Member ID
"{{user.name}}"	First name
"{{user.last_name}}"	Last name
"{{user.login}}"	Login (@username)
"{{user.avatar}}"	Link to user avatar (URL from public storage, e.g., `https://example.com/storage/img/photos/123/abc.jpg`). `null` if no avatar exists
"{{user.phone}}"	Phone number
"{{user.email}}"	Email
"{{user.credits}}"	Credits
"{{user.balance}}"	Available balance
"{{user.bonuses}}"	Bonuses
"{{user.earn}}"	Total earned
"{{user.earn_from_ref}}"	Earnings from referrals
"{{user.status}}"	Status (1 — active, 2 — blocked)
"{{user.ban}}"	Blocked status (0 / 1)
"{{user.sex}}"	Gender ("male" / "female" / "unknown")
"{{user.lang}}"	Language ("ru", "en", etc.)
"{{user.age}}"	Age
"{{user.date_birth}}"	Date of birth
"{{user.place_birth}}"	Place of birth
"{{user.city}}"	City
"{{user.address}}"	Address
"{{user.bio}}"	Biography
"{{user.device}}"	Device
"{{user.tag}}"	Tag
"{{user.pay_until}}"	Payment due date
"{{user.last_payment}}"	Last payment date
"{{user.is_premium}}"	Telegram Premium (0 / 1)

Product

Working with product cards from the built-in store.

Available actions

Action	Description
Get product	Loads product data by ID into a variable (default: "shop")
Change description	Short description
Change long description	Full description text
Change price	Decimal number (e.g., "99.99")
Change old price	Displayed as a crossed-out price
Change SKU	Unique product identifier
Change currency	Select from list (₽, $, €, etc.)
Increase quantity	Adds to stock balance
Decrease quantity	Subtracts from stock balance
Increase sales total	Adds to total sales amount
Decrease sales total	Subtracts from sales amount
Increase orders	Increments order count
Decrease orders	Decrements order count
Increase pending	Increments pending buyer count
Decrease pending	Decrements pending count
Increase views	Adds to view count
Increase cart additions	Adds to cart addition count

Product properties

Variable	Description
"{{shop.id}}"	Product ID
"{{shop.name}}"	Name
"{{shop.description}}"	Description
"{{shop.description_full}}"	Full description
"{{shop.price}}"	Price
"{{shop.old_price}}"	Old price
"{{shop.currency}}"	Currency
"{{shop.amount}}"	Quantity in stock
"{{shop.status}}"	Product status
"{{shop.sku}}"	SKU
"{{shop.orders}}"	Number of orders
"{{shop.summa}}"	Sales total
"{{shop.views}}"	Views
"{{shop.cart_added}}"	Additions to cart
"{{shop.image}}"	Image
"{{shop.video}}"	Video
"{{shop.last_order}}"	Last order
"{{shop.created_at}}"	Creation date

Files

Working with media files from the bot's library.

Available actions

Action	Description
Get file	Loads file data by ID into a variable (default: "file")
Get file by external ID	Loads file data by the "External ID" (out_id) field into a variable (default: "file")
Change name	Sets a new file name
Change description	Text description
Change Telegram description	Caption displayed when sending the file to a chat
Change artist	Artist name (for audio files)
Increment send counter	Step: integer 1–100

File properties

Variable	Description
"{{file.id}}"	File ID
"{{file.name}}"	Name
"{{file.description}}"	Description
"{{file.file_size}}"	File size
"{{file.file_type}}"	File type
"{{file.file_ext}}"	Extension
"{{file.file_telegram_id}}"	Telegram file_id
"{{file.caption}}"	Telegram caption
"{{file.duration}}"	Duration (seconds)
"{{file.width}}"	Width
"{{file.height}}"	Height
"{{file.performer}}"	Performer
"{{file.sent}}"	Number of shipments
"{{file.status}}"	Status
"{{file.votes}}"	Votes
"{{file.rate}}"	Rating
"{{file.out_id}}"	External ID
"{{file.created_at}}"	Creation date

Orders

Managing orders from the built-in store.

Available actions

Action	Description
Get order by ID	Loads order data into a variable (default: "order")
Get orders	Retrieves orders based on filters: status, amount range, dates, etc.
Get user orders	All orders for a specific user
Add order	Creates a new order
Update order	Modifies fields of an existing order
Add item to order	Adds an item to the order
Remove item from order	Removes an item from the order
Change item quantity in order	Sets a new quantity for an item
Delete order	Deletes an order by ID

Order statuses: New · Processing · Awaiting payment · Paid · Shipped · Delivered · Cancelled · Pending · Completed

Order properties

Variable	Description
"{{order.id}}"	Order ID
"{{order.status}}"	Status
"{{order.summa}}"	Amount
"{{order.delivery_cost}}"	Delivery cost
"{{order.delivery_days}}"	Delivery days
"{{order.discount}}"	Discount
"{{order.used_promo}}"	Promo code used
"{{order.delivery_date}}"	Delivery date
"{{order.created_at}}"	Creation date
"{{order.goods}}"	Items in the order (array)

User Config

Stores custom settings linked to a specific bot user. The data structure is an object with keys of your choice.

Available actions

Action	Description
Get user settings	Loads the entire config into a variable (default: "user_config")
Update settings	Modifies the specified keys. Supports nested keys using dot notation, e.g., "settings.theme"
Add settings	Adds only missing keys; does not overwrite existing values
Delete settings	Removes specified keys from the config

Data Access

Once the config is retrieved, fields are accessible using dot notation:

{{user_config.theme}} {{user_config.settings.color}} {{user_config.notifications}}

The block includes a Test button — it loads actual user data and automatically updates the list of available fields for autocomplete.

User Records

Stores arbitrary records linked to a user. Used for action logs, AI conversation history, and any other tasks.

Available Actions

Action	Description
Get all user records	List of records with filters (type, value, date range, limit, sorting). Result stored in the "user_logs" variable
Get all bot records	List of records for the entire bot, not linked to a specific user. Result stored in the "bot_logs" variable
Get record by ID	Loads a single record into a variable (default: "user_log")
Add record	Creates a new record. The ID of the created record is saved to a variable (default: "new_log_id")
Update record	Modifies the fields of an existing record based on its ID
Delete record	Deletes a record based on its ID
Count records	Returns the number of records matching a condition to a variable (default: "user_logs_count")
Clear conversation	Deletes the conversation history within a specified record
Clear all user conversations	Deletes conversation history across all user records
Add to list	Appends a value to the end of the `list` field in a specified record
Update list	Updates an item in the `list` field at a specified index
Remove from list	Removes an item from the `list` field at a specified index

Record Properties

Variable	Description
"{{user_log.id}}"	Record ID
"{{user_log.tg_user_id}}"	User ID
"{{user_log.type}}"	Record type
"{{user_log.name}}"	Name
"{{user_log.value}}"	Value
"{{user_log.total_tokens}}"	Token usage (AI integrations)
"{{user_log.dialog_history}}"	Dialogue history (array of messages)
"{{user_log.dialog_history_count}}"	Number of messages in history
"{{user_log.list}}"	List (array of values)
"{{user_log.list.0}}"	List item value by index (0, 1, 2...)
"{{user_log.list_count}}"	Number of items in the list; defaults to 0
"{{user_log.created_at}}"	Creation date
"{{user_log.updated_at}}"	Update date

For an array of records, access them via index: "{{user_logs[0].value}}", "{{bot_logs[0].type}}", etc.

Payments

Reading records of payments made via the bot.

Available actions

Action	Description
Get payment by ID	Loads payment data into a variable (defaults to "payment")
Get payment by Order ID	Searches for a payment by unique order number
Get user payments	List of payments for a specific user, with status filter and limit
Get all payments	List of all bot payments, with status filter and limit

Payment statuses: Pending · Paid · Error · Expired

Payment properties

Variable	Description
"{{payment.id}}"	Record ID
"{{payment.order_id}}"	Unique order number
"{{payment.status}}"	Status
"{{payment.amount}}"	Amount
"{{payment.currency}}"	Currency
"{{payment.description}}"	Description
"{{payment.pay_url}}"	Link to the payment page
"{{payment.paid_at}}"	Payment date and time
"{{payment.payload}}"	Additional parameters (JSON object)
"{{payment.payload.KEY}}"	Specific additional parameter passed via the payment button

For an array: "{{payments[0].status}}", "{{payments[0].amount}}", etc.

Subscriptions

Reading and modifying records for recurring (periodic) subscriptions.

Available actions

Action	Description
Get all subscriptions	List of subscriptions with filters: user, provider, status, amount, period, date range, limit, and sorting
Get user's active subscription	User's first active subscription. User ID is optional; defaults to the current member
Update subscription status	Changing status to "Cancelled" automatically sets the cancellation date
Update subscription period	Changes the number of days between charges
Update subscription amount	Changes the amount of the next charge
Update subscription currency	Changes the currency (e.g., "RUB", "USD")

Subscription statuses: Pending · Active · Overdue · Failed · Cancelled

Subscription properties

Variable	Description
"{{subscription.id}}"	Subscription ID
"{{subscription.chat_id}}"	User's Telegram chat_id
"{{subscription.tg_user_id}}"	User ID in the bot
"{{subscription.payment_provider_id}}"	Payment provider ID
"{{subscription.card_mask}}"	Last 4 digits of the card
"{{subscription.card_type}}"	Card type (Visa, MasterCard, etc.)
"{{subscription.amount}}"	Charge amount
"{{subscription.currency}}"	Currency
"{{subscription.period_days}}"	Period in days
"{{subscription.max_attempts}}"	Maximum number of charge attempts
"{{subscription.charge_attempts}}"	Number of failed attempts
"{{subscription.status}}"	Status
"{{subscription.payload}}"	Additional data
"{{subscription.next_charge_at}}"	Next charge date
"{{subscription.last_charged_at}}"	Date of last successful charge
"{{subscription.expires_at}}"	Subscription expiration date
"{{subscription.cancelled_at}}"	Cancellation date
"{{subscription.created_at}}"	Creation date
"{{subscription.updated_at}}"	Update date

For an array: "{{subscriptions[0].status}}", "{{subscriptions[0].amount}}", etc.

User Statistics

The User Statistics source allows you to store arbitrary data as key-value pairs linked to a specific user, date, and type. It is useful for recording daily metrics, cumulative values, test results, etc.

Data is stored in the bot_user_stat table. Unique key: bot_id + tg_user_id + date + type. If a record with this combination already exists, its data is updated (updateOrCreate behavior).

Actions

Action	Description
Create record	Creates a new record or updates an existing one for the specified user, date, and type. Data is defined as "name → value" pairs (min. 1 pair).
Get records	Returns a list of records filtered by user, date range, type, limit, and sorting.
Delete user records	Deletes all records for a user, with options to filter by date range and type.

Create record — fields

Field	Required	Description
User ID	✅	User's Telegram ID. Defaults to `{{USER_ID}}`.
Date	✅	Record date in `YYYY-MM-DD` format. Defaults to `{{$NOW.toDate()}}`.
Type	✅	Custom classifier string (e.g., `steps`, `score`, `mood`).
Data	✅	One or more "name → value" pairs. Both fields support variables.

Get records — filters and result

Field	Description
User ID	Filter by user.
Date from	Start of range (inclusive). Defaults to `{{$NOW.subDays(7).toDate()}}`.
Date to	End of range (inclusive). Defaults to `{{$NOW.toDate()}}`.
Type	Filter by type.
Limit	Maximum number of records (1–100; default is 10).
Sort	`date ↓` (newest first) or `date ↑` (oldest first).
Variable prefix	Variable name for storing the result array. Defaults to `result_stat`.

Each element of the resulting array contains the following properties:

Variable	Description
`{{result_stat[0].id}}`	Record ID
`{{result_stat[0].date}}`	Date (YYYY-MM-DD)
`{{result_stat[0].type}}`	Record type
`{{result_stat[0].tg_user_id}}`	Telegram user ID
`{{result_stat[0].data}}`	Data (JSON object)

Delete record — fields

Field	Description
Record ID	ID of the record to delete (e.g., from the "Get records" result).

Delete user records — fields

Field	Required	Description
User ID	✅	Telegram user ID.
Date from	—	Start of the deletion period.
Date to	—	End of the deletion period.
Type	—	Delete only records of the specified type.

Scenario example

Add a Database block and select the User source.
Add the Get user action and specify the "user" variable.
In a "Condition" block, check "{{user.credits}}" — if there are enough credits, proceed to the next step; otherwise, prompt the user to top up.
After payment, add the Database block again and the Add credits action to update the user's balance.

User schedules

The User schedules source allows you to manage personal broadcast schedules for each user. This is necessary if you need to send multiple broadcasts at different times based on the specific user's time zone—for example, morning and evening broadcasts.

How it works with Auto-messages

Enable the Individual schedule option in the "Auto-message" node (General timer → Calendar-based).
Specify the Schedule type, e.g., morning or evening.
The bot will send the message only to users who have a record with that type in the database.
Manage records via the "Database" block → "User schedules" source. If the "Schedule Type" field is left blank, the legacy behavior is used: the preferred_time and preferred_days fields from the user profile.

Actions

Action	Description
Create / update schedule	Adds or updates a record by type. Fields: type, time (HH:MM), days, timezone
Get schedule by type	Returns the record object to a variable or `null`
Get all schedules	Returns an array of all user records
Delete schedule	Deletes the record by type

Schedule object fields (`{{schedule.field}}`)

Field	Description
`{{schedule.id}}`	Record ID
`{{schedule.schedule_type}}`	Schedule type
`{{schedule.time}}`	Time in `HH:MM` format
`{{schedule.days}}`	Days of the week separated by commas (`mon,tue,wed`) or empty = all days
`{{schedule.timezone}}`	IANA timezone or empty (uses the user's timezone)
`{{schedule.created_at}}`	Creation date
`{{schedule.updated_at}}`	Update date

Example: morning and evening broadcasts

Step 1. The user selects a convenient time — the bot saves it:

Database → User schedules → Create/update
Type: morning
Time: {{user_input_time}}  ← e.g., 08:00
Days: mon,tue,wed,thu,fri
Timezone: {{user.timezone}}

Step 2. Create an "Auto-message" node → General timer → Calendar-based:

Enable "Individual schedule"
Schedule type: morning

Step 3. Repeat for the evening broadcast (type evening, time 20:00).

The result: each user receives mailings at exactly the right time for them, and different users may have different scheduled times for the same type of mailing.

Database

Available Sources

User

Available Actions

User properties

Product

Available actions

Product properties

Files

Available actions

File properties

Orders

Available actions

Order properties

User Config

Available actions

Data Access

User Records

Available Actions

Record Properties

Payments

Available actions

Payment properties

Subscriptions

Available actions

Subscription properties

User Statistics

Actions

Create record — fields

Get records — filters and result

Delete record — fields

Delete user records — fields

Scenario example

User schedules

How it works with Auto-messages

Actions

Schedule object fields ({{schedule.field}})

Example: morning and evening broadcasts

Schedule object fields (`{{schedule.field}}`)