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


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.

// this command will be runned after recount
// onComplete: 'onCompleteListRecount'

Calculate the amount of all props and users

Need recount before; // integer value

Properties management

Add property to bot list

Bot property is always add to List for bot

name: 'stringProp',
value: 'Bad Apple',
type: 'string',
list: 'MyList' // bot list will be created if not exist

Add property to user list

User property is always add to List for user

name: "stringProp",
value: "Bad Apple",
type: "string",
list: "MyList" // bot list will be created if not exist

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 or user'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


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