Data Management & States

Bots.LT provides a built-in Key-Value (KV) store with three scopes for String/JSON data, a Resource system for numeric data (like coins/points), and a wait state system for multi-step conversations. No external database is needed.

1. String & JSON Data (Properties)

This system is ideal for storing text, configurations, and complex JSON data. Data is stored and retrieved using three scope objects, each with the same set of methods.

Scopes

Scope	Object	Description
User	`User`	Data stored per user (keyed by `user_id`). Each user has their own isolated data.
Bot	`Bot`	Data stored globally for the entire bot. Shared across all users.
Account	`Account`	Data shared across all bots owned by the developer. (Legacy alias: `Api`)

User Data Methods

The User object isolates data specifically for the individual interacting with your bot.

User.saveData

Saves a value for the current user. (Aliases: setProperty, setProp)

Parameter	Type	Required	Description
`key`	String	Yes	The key name to store data under.
`value`	Any	Yes	The value to store.

BLP Example

User.saveData("name", "John Doe")
User.setProperty("language", "English")

User.getData

Retrieves a stored value for the current user. Returns None if it does not exist. (Aliases: getProperty, getProp)

Parameter	Type	Required	Description
`key`	String	Yes	The key to retrieve.

BLP Example

name = User.getData("name")
if name:
    Bot.sendMessage(chat_id=u, text=f"Welcome back, {name}!")

User.deleteData

Deletes a key from the user’s data. (Aliases: deleteProperty, deleteProp)

Parameter	Type	Required	Description
`key`	String	Yes	The key to delete.

BLP Example

User.deleteData("temp_token")

User.getDataFile

Exports a specific user value as a downloadable file.

Parameter	Type	Required	Description
`name`	String	Yes	The key to export.
`output_format`	String	No	`"txt"` or `"json"`. Default: `"txt"`.

BLP Example

file = User.getDataFile("settings", output_format="json")
Bot.sendDocument(chat_id=u, document=file)

User.getAllData

Gets all user keys matching a pattern across all users, returning a file.

Parameter	Type	Required	Description
`name`	String	Yes	Pattern to match keys.
`output_format`	String	No	`"json"` or `"txt"`. Default: `"json"`.

BLP Example

# Get all 'order' keys from all users
file = User.getAllData("order", output_format="json")
Bot.sendDocument(chat_id=u, document=file)

User.getAllDataOfUser

Exports all data stored for a specific user.

Parameter	Type	Required	Description
`user`	Integer	Yes	The user ID to export data for.
`output_format`	String	No	`"json"` or `"txt"`. Default: `"json"`.

BLP Example

file = User.getAllDataOfUser(u, output_format="json")
Bot.sendDocument(chat_id=u, document=file, caption="All your data")

Bot Data Methods

The Bot object stores global data that is shared across all users in the same bot.

Bot.saveData

Saves a value globally for the bot.

Parameter	Type	Required	Description
`key`	String	Yes	The key name to store data under.
`value`	Any	Yes	The value to store.

BLP Example

Bot.saveData("announcement", "New features launched!")

Bot.getData

Retrieves a stored value for the bot. Returns None if it does not exist.

Parameter	Type	Required	Description
`key`	String	Yes	The key to retrieve.

BLP Example

announcement = Bot.getData("announcement")
if announcement:
    Bot.sendMessage(chat_id=u, text=f"📢 {announcement}")

Bot.deleteData

Deletes a key from the bot’s data.

Parameter	Type	Required	Description
`key`	String	Yes	The key to delete.

BLP Example

Bot.deleteData("temporary_maintenance_flag")

Bot.getDataFile

Exports a specific bot value as a downloadable file.

Parameter	Type	Required	Description
`name`	String	Yes	The key to export.
`output_format`	String	No	`"txt"` or `"json"`. Default: `"txt"`.

BLP Example

file = Bot.getDataFile("config_rules")
Bot.sendDocument(chat_id=u, document=file)

Bot.getAllData

Gets all bot keys matching a pattern, returning a file.

Parameter	Type	Required	Description
`name`	String	Yes	Pattern to match keys.
`output_format`	String	No	`"json"` or `"txt"`. Default: `"json"`.

BLP Example

file = Bot.getAllData("", output_format="json") # Export everything
Bot.sendDocument(chat_id=u, document=file)

Bot.getBotUsersFile

Exports the full list of users who have interacted with the bot.

Parameter	Type	Required	Description
`output_format`	String	No	`"json"` or `"csv"`. Default: `"json"`.
`include_creation_date`	Boolean	No	If `True`, includes the date the user first interacted.
`include_last_active_date`	Boolean	No	If `True`, includes the last activity date.

BLP Example

file = Bot.getBotUsersFile(output_format="csv", include_creation_date=True)
Bot.sendDocument(chat_id=u, document=file, caption="Bot Users Report")

Account Data Methods

The Account object stores data at the developer account level, making it accessible across all bots you own.

Account.saveData

Stores data at the account level, accessible across all bots.

Parameter	Type	Required	Description
`name`	String	Yes	Name identifier for the data.
`data`	Any	Yes	The data to store.

BLP Example

result = Account.saveData("global_settings", {"theme": "dark", "notifications": True})
Bot.sendMessage(chat_id=u, text=f"Save result: {result['result']}")

Account.getData

Retrieves previously stored account data.

Parameter	Type	Required	Description
`name`	String	Yes	Name of the data to retrieve.

BLP Example

settings = Account.getData("global_settings")
if settings:
    Bot.sendMessage(chat_id=u, text=f"Theme: {settings['theme']}")

Account.deleteData

Deletes account data by name.

Parameter	Type	Required	Description
`name`	String	Yes	Name of the data to delete.

BLP Example

result = Account.deleteData("temp_data")
Bot.sendMessage(chat_id=u, text=f"Delete result: {result['result']}")

Account.getDataFile

Returns account data as a file that can be sent to users.

Parameter	Type	Required	Description
`name`	String	Yes	Name of the data to retrieve.
`output_format`	String	No	Format of the output file (e.g. `"txt"`, `"json"`). Default: `"txt"`.

BLP Example

file = Account.getDataFile("report_data")
Bot.sendDocument(chat_id=u, document=file)

Account.getAllData

Retrieves all account data entries, optionally filtered by name pattern.

Parameter	Type	Required	Description
`name`	String	No	Name pattern to filter data.
`output_format`	String	No	Format of the output file. Default: `"json"`.

BLP Example

data_file = Account.getAllData("config_")
Bot.sendDocument(chat_id=u, document=data_file)

Account.deleteAllData

Deletes all account data, with optional exclusions.

Parameter	Type	Required	Description
`except_data`	Array of String	No	List of data names to preserve.
`include_bot_data`	Boolean	No	Ignored (legacy parameter).

BLP Example

result = Account.deleteAllData(except_data=["important_settings"])
Bot.sendMessage(chat_id=u, text=f"Data cleared: {result['result']}")

Account.info

Returns basic account information for the developer.

Parameter	Type	Required	Description
(none)	—	—	No parameters.

BLP Example

info = Account.info()
Bot.sendMessage(chat_id=u, text=f"Account plan: {info.plan}, Points left: {info.points_left}")

2. Numeric Data (Resources)

Manage virtual balances, point systems, and leaderboards — without writing any database queries. This is the recommended way to handle numbers and math-based data.

Accessing Resources

Method	Description
`Libs.Resources.userRes(name)`	Resource for the current user.
`Libs.Resources.anotherRes(name, user_id)`	Resource for a specific user (by `user_id`).
`Libs.Resources.globalRes(name)`	Shared resource for the entire bot.
`Libs.Resources.accountRes(name)`	Shared resource across all bots you own.

Resource Methods

Once accessed, each resource object supports:

Method	Description
`.value()`	Returns current value as Integer or Float.
`.add(amount)`	Adds `amount` to the resource.
`.cut(amount)`	Subtracts `amount` from the resource.
`.set(amount)`	Sets resource to an exact value.
`.reset()`	Resets value to `0`.

BLP Example

# Get current user's coins
coins = Libs.Resources.userRes("coins")

current = coins.value()
Bot.sendMessage(chat_id=u, text=f"💰 You have {current} coins")

# Reward coins
coins.add(50)

# Deduct coins
if coins.value() >= 10:
    coins.cut(10)
    Bot.sendMessage(chat_id=u, text="You spent 10 coins!")
else:
    Bot.sendMessage(chat_id=u, text="Not enough coins!")

BLP Example (Leaderboard)

# Get the top 10 users by "points"
top = Libs.Resources.getTop("points", limit=10)
lines = [f"{i+1}. User {r['user_id']}: {r['value']} pts" for i, r in enumerate(top)]
Bot.sendMessage(chat_id=u, text="\n".join(lines))

BLP Example (Shared Global Counter)

# Increment a global visits counter for a single bot
visits = Libs.Resources.globalRes("total_visits")
visits.add(1)
Bot.sendMessage(chat_id=u, text=f"Total bot visits: {visits.value()}")

BLP Example (Account Resource)

# Share a point pool across ALL bots you own
account_points = Libs.Resources.accountRes("subscription_points")

# Add points
new_value = account_points.add(100)
Bot.sendMessage(chat_id=u, text=f"Added points. New value: {new_value}")

# Use points
account_points.cut(50)
Bot.sendMessage(chat_id=u, text=f"Used 50 points. Remaining: {account_points.value()}")

3. Wait States (Conversational Flows)

Use wait states to build multi-step conversations — asking users for input one step at a time, like forms, quizzes, or registration wizards.

Bot.handleNextCommand

Routes the user’s next message to a specific command, regardless of what they type.

Parameter	Type	Required	Description
`command_name`	String	Yes	Command to trigger on next user message (e.g., `"/save_name"`).
`options`	Dict	No	Optional data dictionary forwarded to the next command. Access via `options.get("key")`.
`cancel_at_command`	Boolean	No	If `True`, wait state is cancelled when user sends a new command like `/start`. Default: `True`.

BLP Example (2-step registration)

# Command: /start
Bot.sendMessage(chat_id=u, text="👋 What is your name?")
Bot.handleNextCommand("/save_name")

# Command: /save_name
name = message.text
User.saveData("name", name)
Bot.sendMessage(chat_id=u, text=f"✅ Hello, {name}! Now enter your email:")
Bot.handleNextCommand("/save_email", {"name": name})

# Command: /save_email
name = options.get("name")
email = message.text
User.saveData("email", email)
Bot.sendMessage(
    chat_id=u,
    text=f"✅ Registration complete!\nName: {name}\nEmail: {email}"
)

BLP Example (Passing data between steps)

# Step 1: /ask_amount
Bot.sendMessage(chat_id=u, text="How many coins do you want to buy?")
Bot.handleNextCommand(
    "/confirm_purchase",
    {"product": "Premium Pack", "price_per": 10},
    cancel_at_command=True
)

# Step 2: /confirm_purchase
amount = int(message.text)
product = options.get("product")
price_per = options.get("price_per")
total = amount * price_per

keyboard = [[
    InlineKeyboardButton(text="✅ Confirm", callback_data=f"buy_{amount}"),
    InlineKeyboardButton(text="❌ Cancel", callback_data="cancel")
]]

Bot.sendMessage(
    chat_id=u,
    text=f"Buy {amount}x {product} for {total} coins?",
    reply_markup=InlineKeyboardMarkup(inline_keyboard=keyboard)
)

Getting Started

Language Reference

Telegram API Methods

Core Libraries (Libs)

Advanced & Tools

Data Management & States

1. String & JSON Data (Properties)

Scopes

User Data Methods

User.saveData

User.getData

User.deleteData

User.getDataFile

User.getAllData

User.getAllDataOfUser

Bot Data Methods

Bot.saveData

Bot.getData

Bot.deleteData

Bot.getDataFile

Bot.getAllData

Bot.getBotUsersFile

Account Data Methods

Account.saveData

Account.getData

Account.deleteData

Account.getDataFile

Account.getAllData

Account.deleteAllData

Account.info

2. Numeric Data (Resources)

Accessing Resources

Resource Methods

3. Wait States (Conversational Flows)

Bot.handleNextCommand

​1. String & JSON Data (Properties)

​Scopes

​User Data Methods

​User.saveData

​User.getData

​User.deleteData

​User.getDataFile

​User.getAllData

​User.getAllDataOfUser

​Bot Data Methods

​Bot.saveData

​Bot.getData

​Bot.deleteData

​Bot.getDataFile

​Bot.getAllData

​Bot.getBotUsersFile

​Account Data Methods

​Account.saveData

​Account.getData

​Account.deleteData

​Account.getDataFile

​Account.getAllData

​Account.deleteAllData

​Account.info

​2. Numeric Data (Resources)

​Accessing Resources

​Resource Methods

​3. Wait States (Conversational Flows)

​Bot.handleNextCommand

1. String & JSON Data (Properties)

Scopes

User Data Methods

User.saveData

User.getData

User.deleteData

User.getDataFile

User.getAllData

User.getAllDataOfUser

Bot Data Methods

Bot.saveData

Bot.getData

Bot.deleteData

Bot.getDataFile

Bot.getAllData

Bot.getBotUsersFile

Account Data Methods

Account.saveData

Account.getData

Account.deleteData

Account.getDataFile

Account.getAllData

Account.deleteAllData

Account.info

2. Numeric Data (Resources)

Accessing Resources

Resource Methods

3. Wait States (Conversational Flows)

Bot.handleNextCommand