Use Lists to store large amounts of data. List is a quick way to get and search data. Also list is preferred way for organize statistics.
List - it is a collection of properties or users.
  • history (orders history, transactions, payments history, locations history, etc)
  • large price lists
  • table of cities with population
  • results for Inline Bot
  • referrals list
Do not use JSON property to collect a large array. This is a very bad practice.
"Execution timeout" error - it is typical error if you use JSON prop for large data.
Use a List.

List initialization

Before using the list (new or existing), you need to initialize it.
List can be global for Bot:
let list = new List({ name: "MyList" })
Bot.inspect(list.exist) // false for new List, true for already exist list
or can be personal for user:
let list = new List({ name: "MyList", user: user })
// or for user id
let list = new List({ name: "MyList", user_id: })
After it you can perform another list methods

Create new list

// for list saving

Remove list


Recount list

Recalculate all statistical data in list.
Can spent 5-30 seconds and more for big list. So you need perform this task on background once in week/day or hour.
if (list.isRecountNeeded()) {
// this command will be runned after recount
// onComplete: 'onCompleteListRecount'
you can get delay time in ms:
// total delay in ms
// need to wait for next recount in ms
recount lag:
// you can change lag for next recount
// it is 1000 ms by default
// prefer to use 1000 - 2000
list.recount_delay.lag = 1000;

Calculate the amount of all props and users

Need recount before
list.count; // integer value

Properties management

Add bot property to bot list

Bot property can be added to List for bot
Example. Bot can have price list.
name: 'product1',
value: 'Nano Cloud',
type: 'string',
list: 'PaidPlans' // bot list will be created if not exist

Add user property to user list

User property can be added to List for user
Example. User can have Orders list
name: "order125",
value: { product_id: "product1", price: 28 },
type: "json",
list: "Orders", // bot list will be created if not exist

Add user property to bot list

User property can be added to List for bot
Example. Bot can have top customers list.
let list = new List({ name: "TopCustomers" })
if(!list.exist){ list.create() }
name: "customer" +,
value: 20, // total income in USD
type: "float",
list: list,
// you can set this prop for other user also:
// user_id:

Reject property

Reject property from list without destroying by prop name

Remove property

Reject property from list and destroy it by prop name

Reject all properties (and all users)

Reject all properties from list
this method reject all properties and all users from list

Remove all properties (and reject all users)

Remove all properties from list
this method remove all properties and reject all users from list

Users management

Add user

// or if you have id only
// list.addUser({ id: });

Reject user

Reject user from list
// or by id
list.rejectUser({ id: });

Reject all users

Reject all users from list

Getting data

Getting props from list

let props = list.get();
/* result will be like:
"name": "stringProp",
"value": "Bad Apple",
"user": {
"id": null
"created_at": "2020-11-09T01:46:52.270Z",
"updated_at": "2020-11-09T01:46:52.270Z"

Getting users from list

let users = list.getUsers();


We have pages for data. Data is given page by page from the first page.
One page have 100 items by default.
// page 1
let props = list.get();
let users = list.getUsers();
// page 2 = 2
props = list.get(); // getting props from page 2
users = list.getUsers(); // getting users from page 2
// it is possible to change default per page
list.per_page = 10 // 100 by default
// total pages
let total_pages = list.total_pages;


Default order is ascending by id (prop's id)
// default order is ascending by id
let props = list.get();
props[0] // oldest prop in list
// Change order to descending:
list.order_ascending = false;
props[0] // newest prop in list
Ordering method can be changed from id (default) to other method:
list.order_by = "integer_value";
// list.order_by = "user_id";
// list.order_by = "size";
// etc - see table
list.order_ascending = true;
props[0] // prop with lowest value
Ordering props by
order by user_id
order by name
order by integer value
order by float value
order by datetime value
order by boolean value
order by string value
order by text value
ordering by value type (integer, float and etc)
order by value size

Users ordering

let users = list.getUsers();
// you can order users only by user id
list.order_ascending = false;


Searching for text props

Searching is available for list's properties. (String and text props)
// search prop with text value "Apple"
// case sensetive by default
let props ="Apple");
// case insensentive
list.case_sensitive = false;
// search props with text value "Apple", "apple", "aPpLe" and etc
props ="Apple");
// search props started with text "apple"
props ="%Apple");
// search props ended with text "apple"
props ="Apple%");
// search props contains text "apple"
props ="%Apple%");
  • Percent sign ( %) matches any sequence of zero or more characters.
  • Underscore sign ( _) matches any single character.
Ordering and paginating also works with searching = 2;
list.order_ascending = false;
let props ="Apple");

User searching

Getting user by id from list

// getting user from list if exist
list.getUser({ id: })

Checking the user's existence in the list

// or by id:
list.haveUser({ id: })


Is available for integer and float props
Need recount before
list.count // total props + users count
list.total_value // sum of all props
list.average_value // average of all props