Variables, tables and lists

Where to store data¶

1. Variable — one value: a conversation stage, counter or setting.
2. Table — records with columns: requests, products or members.
3. Step result — temporary data for the current run.

Use the same scope for reading and writing. Bot shares data, flow belongs to one flow, and chat belongs to a conversation. In a group, chat scope is not private memory for each member.

Check search filters before updating or deleting rows. Changes persist between runs.

More about scopes and chips →

Get chat history¶

Reads the stored history of the current chat, for example to provide AI context.

1. Choose a recent message count or a time period. Exclude commands and bot messages if needed.
2. The result is a list of messages available to botnest, not arbitrary older Telegram conversations.

Random list item¶

Picks one random item from a list.

1. Supply a non-empty list and name the result.
2. Use the selected item in the next step. To process every item, use For each item instead.

Insert table row¶

Adds a new row to a table.

1. Choose the table and data scope. Fill its columns with values or chips.
2. Each run creates a new row. Use Insert or update row when repeated runs should update an existing record.

Update table rows¶

Changes values in rows matching your filters.

1. Choose a table, set filters and specify the columns to update.
2. Check filters before running: multiple rows may change at once. Preview matches with Find table rows first.

Insert or update row¶

Updates a matching record or creates one if none matches.

1. Choose a table and a filter identifying the record, such as a user ID.
2. Fill in the column values. Use Insert table row when every run should create an independent record.

Delete table rows¶

Deletes rows matching your filters.

1. Choose a table and precise filters. Check the matches with Find table rows first.
2. Deletion changes stored data. Do not test it on important records without a copy.

Find table rows¶

Finds matching table rows and returns a list.

1. Choose the table, filters, sorting and row limit.
2. The list is in the result's rows field, such as ${table_result.rows}. Pass it to a loop; no matches means an empty list.

Get table row by ID¶

Gets one table row by its internal ID.

1. Choose the table and supply a row ID from an earlier result.
2. A row ID is not a user or chat ID. Use Find table rows to search by a column value.

Read variable¶

Reads a stored variable.

1. Set its name, type and scope: the whole bot, one flow or the current chat.
2. Use the same name and scope when reading and writing. Add a check for values that have not been set yet.

Set variable¶

Stores a value between flow runs.

1. Set a name, type, scope and new value. For example, store a conversation stage in the current chat scope.
2. Writing replaces the previous value. Bot-scoped data is shared across all of its chats.

Increment variable¶

Increases a stored numeric variable.

1. Set the name, scope and increment, such as 1 for a counter.
2. Use a numeric type. For a calculation without storing a variable, use Add numbers.

Decrement variable¶

Decreases a stored numeric variable.

1. Set the name, scope and decrement amount.
2. Add a condition if the value must not become negative. Decrementing alone does not establish a lower limit.