README

LSK.js – bots

@lskjs/bots – LSK.js module for telegram, slack, discord, whatsapp, twitter, instagram and vk bots creation

⌨️ Install
Bots Plugin Portal
Bots Plugin Interview
- Interview
- Portal
📖 License
👥 Contributors
👏 Contributing
📮 Any questions? Always welcome :)

⌨️ Install

# yarn
yarn i @lskjs/bots @lskjs/db axios bluebird lodash

# npm
npm i @lskjs/bots @lskjs/db axios bluebird lodash

Bots Plugin Portal

Bots Plugin Portal (@lskjs/bots-plugin-portal) - плагин, позволяющий настраивать реакции бота на различные триггеры.

Конфиг плагина находится по пути bots.plugins.portal и имеет вид:

bots: {
  plugins: {
    portal: {
      group: true,
      rules: [
        //...
      ],
    },
  },
},

Params:

Field	Type	Desription
group	Boolean	Группировать ли медиа-файлы
rules	Array of Objects	Массив правил, которым следует бот при обработке входящих сообщений или при срабатывании крона

Group values:

Field	Value	Description
group	true	Группирует медиа-файлы в одно сообщение и помещает их в `ctx.group`
group	false	Медиа-файлы приходят на сервер разными сообщениями

/Reference/: При отправке боту нескольких медиа-файлов одним сообщением, на сервер медиа-файлы приходят разными сообщениями. Т.е. при отправке 5 изображений одним сообщением, на сервер приходит не одно сообщение, а 5.

Правила (rules)

Правила позволяют устанавливать триггеры на действия пользователей или на срабатывание крона. Представляют из себя объекты и могут быть вложены друг в друга.

Правила состоят из 3-х частей: | Rule Part | Type | Required | Description | | ------ | :------: | :------: | ------ | | cron | Array of String\String | - | Позволяет устанавливать расписания срабатываний экшона | |criteria| Object | - | Критерии срабатывания экшона при обработке действий пользователя | | action | Object | + | Экшоны. Описания действий, которые выполняет бот |

`cron`

Параметр позволяет устанавливать время срабатывания действия бота. Например, если необходимо установить отправку сообщений в чат каждую минуту, то конфиг будет выглядеть cron: '* * * * *'.

Официальный пакет крона: node-cron - npm

`criteria`

Параметр позволяет устанавливать критерии на триггеры срабатывания бота. Например, если необходимо, чтобы бот реагировал только на сообщения в определенном чате, то критерий будут выглядеть chatId: 12345678.

Если criteria отсутствует, то правила могут срабатывать только по крону. Если же criteria: {}, то считается, что критерий отбора нет и правила будут срабатывать на любые взаимодействия с ботом.

`action`

Параметр задает действия бота. Здесь настраивается, будет бот искать сообщения, оправлять или удалять их и тд.

Действия могут быть вложенными и составлять цепочки при помощи полей then и else. При удачном выполнении действия-родителя бот будет выполнять действия из поля then. При неудачном - else. Аналогия с if/else, где if - then, а else - else. Например, при проверке checkMessage, если сообщение существует, то бот пройдет по ветке then, в противном случае по else.

Кроме вложенности, action/then могут быть массивами и содержать параллельные действия.

Examples:

{
  cron: '* * * * *',
  criteria: {
    chatId: 12345678,
  },
  action: {
    type: 'checkMessage',
    chatId: -123114346456,
    userId: 12345678,
    then: {
      type: 'sendMessage',
      text: 'some text by true checkMessage',
      to: 12345678,
    },
    else: {
      type: 'sendMessage',
      text: 'some text by false checkMessage',
      to: 12345678,
    },
  },
},

{
  cron: ['*/20 * * * *', '*/15 * * * * *'],
  action: [
    {
      type: 'sendMessage',
      text: 'some text 1',
      to: 12345678,
    },
    {
      type: 'sendMessage',
      text: 'some text 2',
      to: -87654321123,
    },
  ],
}

{
  criteria: {
    chatId: 12345678,
  },
  action: {
    type: 'reply',
    text: 'some text by reply',
  },
},

Параметры, используемые при настройке критериев:

Criteria Field	Type	Values	Description
userId	Array of Number\Array of String\Number\String		ID пользователя, который взаимодействует с ботом
chatId	Array of Number\Array of String\Number\String		ID чата, в котором происходит взаимодействие с ботом
chatType	String	private\group\supergroup\channel	Тип чата, в котором происходит взаимодействие
messageType	String		Тип сообщения. Различают множество типов сообщений
messageText	String\RegExp		Текст сообщения. Например, можно сделать критерий на команду запуска бота `messageText: /start`
nextRoute	String\RegExp		Следующий роут. Используется только при заполнении формы. Необходимо устанавливать данный критерий для блокировки каких-либо действий во время заполнения формы в целях избежать спама и лишних триггеров.

Chat types:

private - личные диалог с ботом
group - общий чат
supergroup - общий чат
channel - канал

Message types:

mediaGroup - группа медиа-файлов
audio - приложен аудио-файл
document - приложен документ
animation - гифка
photo - приложено изображение
sticker - стикер
video - приложено видео
video_note - видео-кружочек
voice - голосовое сообщение
contact - контакт
dice - игральная кость
game - игра
poll - голосование
quiz - викторина
location - геоданные
venue - место
text - текстовое сообщение

Список действий, которые реализованы в плагине:

createMessage - создание сообщений
messageAppend - добавление текста в конец
messageTrim - фильтр текста
messageEditExtra - редактирование кнопок
messageAddExtra - добавление кнопок
sendMessage - отправка сообщений
reply - реплай
repost - репост
copyMessage - копирование сообщений
remove - удаление сообщений
findMessage - поиск сообщения
pinChatMessage - закрепление сообщения
messageSplit - разделение сообщения на элементы
messagesJoin - группировка сообщений в одно
checkInterview - проверка заполнения формы
replyInterview - отправка формы

createMessage

createMessage - действие бота, необходимое для создания сообщения и последующего редактирования перед отправкой. После создания сообщения, к нему можно добавить/изменить кнопки, отредактировать его текст и тд.

При срабатывании createMessage от крона, создается пустое сообщение, которое можно заполнять различным контентом.
При срабатывании createMessage от действия пользователя, сообщение создается на основе входящих данных. Т.е. в текст созданного сообщения помещается текст, написанный пользователем. С кнопками и файлами происходят аналогичные действия.

Params:

Field	Type	Description
text	String	текст сообщения
to	Array of Number\Array of String\Number\String	ID чата, в который будет отправлено сообщение

Example:

{
  criteria: {},
  action: {
    type: 'createMessage',
    text: "It's field from message text",
    to: 12345678,
  },
},

messageAppend

messageAppend - действие бота, позволяющее добавить текст в конец сообщения.

Params:

Field	Type	Description
text	String	Добавочный текст

Example:

{
  criteria: {
    messageText: /\/trim/,
  },
  action: {
    type: 'messageAppend',
    text: 'by @download4bot',
    then: {
      type: 'repost',
      to: 12345678,
    },
  },
},

messageTrim

messageTrim - действие бота, позволяющее отфильтровать текст сообщения.

Params:

Field	Type	Description
hashtags	Boolean	Удаляет все хештеги из текста сообщения
links	Boolean	Удаляет все ссылки из текста сообщения
regExp	RegExp	Позволяет удалять любые пользовательские шаблоны из текста сообщения

Example:

{
  criteria: {
    messageText: /\/trim/,
  },
  action: {
    type: 'messageTrim',
    hashtags: 1,
    links: 1,
    regExp: /1?123\n?/,
    then: {
      type: 'repost',
      to: 12345678,
    },
  },
},

messageEditExtra

messageEditExtra - действие бота, позволяющее отредактировать клавиатуру сообщения.

Params:

Field	Type	Description
extra	Array	Содержит редактируемые кнопки клавиатуры

Extra params for type LIKE:

Field	Type	Required	Description
type	String	+	Кнопки лайк/дисслайк к сообщению
buttons	Array	-	Содержит редактируемые кнопки клавиатуры
buttons.disslike	Object	-	Настройка кнопки дисслайка
buttons.like	Object	-	Настройка кнопки дисслайка

Extra params for type ANSWER:

Field	Type	Required	Description
type	String	+	Кнопка для установления соединения с другим пользователем через бота (чат)
text	String	-	Настройка текста кнопки

Extra params for type SENDER:

Field	Type	Required	Description
type	String	+	Кнопка для перехода к отправителю сообщения
text	String	-	Настройка текста кнопки

Example:

{
  criteria: {}
  action: {
    type: 'createMessage',
    text: 'Title text',
    then: {
      type: 'messageEditExtra',
      extra: [
        {
          type: 'like',
          buttons: {
            disslike: {
              title: 'test 💔', // default: '💔'
              value: 10, // default: 0
            },
            like: {
              title: 'test ❤️', // default: '❤️'
              value: 0, // default: 0
            },
          },
        },
        {
          type: 'answer',
          text: 'Answer @{ {username} }', // default: '@username'
        },
        {
          type: 'sender',
          text: 'Sender: @{ {username} }', // default: '@username'
        },
      ],
      then: {
        type: 'sendMessage',
        to: 12345678,
      },
    },
  },
},

messageAddExtra

messageAddExtra - действие бота, позволяющее добавить новую клавиатуру сообщения. Если клавиатура уже существует, то messageAddExtra заменит текущую на новую.

Params: | Field | Type | Description | | ------ | :------: | ------ | | extra | Array | Содержит редактируемые кнопки клавиатуры |

Extra params for type LIKE:

Field	Type	Required	Description
type	String	+	Кнопки лайк/дисслайк к сообщению
buttons	Array	-	Содержит редактируемые кнопки клавиатуры
buttons.disslike	Object	-	Настройка кнопки дисслайка
buttons.like	Object	-	Настройка кнопки дисслайка

Extra params for type ANSWER:

Field	Type	Required	Description
type	String	+	Кнопка для установления соединения с другим пользователем через бота (чат)
text	String	-	Настройка текста кнопки

Extra params for type SENDER:

Field	Type	Required	Description
type	String	+	Кнопка для перехода к отправителю сообщения
text	String	-	Настройка текста кнопки

Example:

{
  criteria: {}
  action: {
    type: 'createMessage',
    text: 'Title text',
    then: {
      type: 'messageAddExtra',
      extra: [
        {
          type: 'like',
          buttons: {
            disslike: {
              title: 'New disslike  💔', // default: '💔'
              value: 10, // default: 0
            },
            like: {
              title: 'New like  ❤️', // default: '❤️'
              value: 0, // default: 0
            },
          },
        },
        {
          type: 'answer',
          text: 'Answer @{ {username} }', // default: '@username'
        },
        {
          type: 'sender',
          text: 'Sender: @{ {username} }', // default: '@username'
        },
      ],
      then: {
        type: 'sendMessage',
        to: 12345678,
      },
    },
  },
},

sendMessage

sendMessage - действие бота, при котором бот отправляет сообщение заданному пользователю. Для настройки сообщения используется цепочка действий: createMessage -> messageAddExtra -> messageAppend -> messageTrim -> sendMessage.

Params:

Field	Type	Required	Description
text	String	-	Текст сообщения
to	Array of String/Array of Number/String/Number	-	ID получателя(-ей)

Example:

{
  criteria: {},
  action: {
    type: 'createMessage',
    then: {
      type: 'sendMessage',
      text: 'Text by sendMessage',
      to: 12345678,
    },
  },
},

reply

reply - действие бота, при котором бот отвечает на сообщение пользователя.

Params:

Field	Type	Required	Description
text	String	-	Текст сообщения

Example:

{
  criteria: {
    messageText: 'ping',
  },
  action: {
    type: 'reply',
    text: 'pong',
  },
},

repost

repost - действие бота, при котором бот пересылает активное сообщение в заданных чат.

Params:

Field	Type	Required	Description
to	Array of String/Array of Number/String/Number	-	ID получателя(-ей)

Example:

{
  criteria: {
    chatId: -136512436512436,
  },
  action: {
    type: 'repost',
    to: 12345678,
  },
},

copyMessage

sendMessage - действие бота, при котором бот копирует активное сообщение и пересылает его в заданных чат.

Params:

Field	Type	Required	Description
to	Array of String/Array of Number/String/Number	-	ID получателя(-ей)

Example:

{
  criteria: {
    chatId: -136512436512436,
  },
  action: {
    type: 'copyMessage',
    to: 12345678,
  },
},

remove

remove - действие бота, при котором бот удаляет активное сообщение. Активным сообщением является полученное сообщение, либо найденное при помощи findMessage.

Example:

{
  criteria: {
    messageText: 'попит',
  },
  action: {
    type: 'remove',
  },
},

findMessage

findMessage - действие бота, позволяющее найти сообщение в чате по заданным параметрам. Поиск осуществляется в модели BotsTelegramMessageModel.

Params:

Field	Type	Required	Description
random	Boolean	-	Если нашлось несколько сообщений, выбирать ли случайное. По умолчанию: последнее полученное ботом сообщение.
criteria	Object	-	Критерии поиска сообщения в базе
criteria.userId	Array of Number\Array of String\Number\String	-	ID пользователя
criteria.chatId	Array of Number\Array of String\Number\String	-	ID чата
criteria.chatType	String	-	Тип чата
criteria.messageType	String	-	Тип сообщения
criteria.messageDate	Number	-	Дата сообщения в ms
criteria.messageText	String\RegExp	-	Текст сообщения
criteria.messageId	String\RegExp	-	ID сообщения

Example:

{
  criteria: {
    messageText: '/checkMessage',
  },
  action: {
    type: 'findMessage',
    criteria: {
      chatId: -1232343354655,
      messageText: '*message.text',
    },
    then: {
      type: 'repost',
      to: 12345678,
    },
  },
},

pinChatMessage

pinChatMessage - действие бота, при котором бот закрепляет активное сообщение. Активным сообщением является полученное сообщение, либо сообщение после findMessage/createMessage.

Example:

{
  criteria: {
    messageText: /^#закрепить.*/,
  },
  action: {
    type: 'pinChatMessage',
  },
},

messageSplit

messageSplit - действие бота, позволяющее разделять входящее сообщение на элементы для последующей работы. Например, если пользователь пишет боту сообщение, содержащее 5 изображений и подпись, то бот разделит сообщение на 6 элементов.

Example:

{
  criteria: {},
  action: {
    type: 'messageSplit',
    then: {
      type: 'sendMessage',
      to: 12345678,
    },
  },
},

messagesJoin

messagesJoin - действие бота, позволяющее объединять несколько сообщений, переданных боту (например, пересылая сообщения). Если среди сообщений несколько подписей, то они объединятся в единый текст.

Example:

{
  criteria: {},
  action: {
    type: 'messagesJoin',
    then: {
      type: 'sendMessage',
      to: 12345678,
    },
  },
},

checkInterview

checkInterview - действие бота для проверки, заполнил ли пользователь необходимые формы.

Params:

Field	Type	Description
type	String	Тип действия бота. Запускает проверку на заполненность формы
forms	Array of String/String	Список с названиями форм, которые следует заполнить для прохождения проверки

Example:

{ 
  criteria: {
    messageText: /^(?!\/registration).*$/,
    nextRoute: /^(?!\/interview).*$/,
  },
  action: {
    type: 'checkInterview',
    forms: ['intro'],
    then: [
      type: 'reply',
      text: 'Успех!',
    ],
    else: {
      type: 'reply',
      text: 'Необходима регистрация! /registration'
    },
  },
},

replyInterview

replyInterview - действие бота для отправки формы пользователю.

Params:

Field	Type	Value	Description
type	String		Тип действия бота. Отправляет форму пользователю
formName	String		Название формы, которая будет отправлена пользователю
mode	String	form/dialog	Режим работы формы
preview	Boolean		Параметр, который указывает, необходимо ли выводить title формы перед вводом данных
autosubmit	Boolean		Параметр, который указывает, необходимо ли подтверждение данных формы

Example:

{
  criteria: {
    chatType: 'private',
    messageText: '/registration',
  },
  action: {
    type: 'replyInterview',
    formName: 'intro',
    mode: 'form',
    preview: false,
    autosubmit: false,
    then: {
      type: 'reply',
      text: 'Успех!',
    },
  },
},

Bots Plugin Interview

Bots Plugin Interview (@lskjs/bots-plugin-interview) - плагин, позволяющий создавать формы ввода в боте. Реализована вариация с классической браузерной формой с подтверждением введенных данных. Режим диалога находится в стации разработки.

Конфиг для плагина состоит из двух частей - interview и portal. Interview отвечает за настройку формы, её полей и их валидацию. Portal реализует взаимодействие с формой. Например, при каких действиях пользователя будет вызвана форма.

Входные данные сохраняются в базу и хранятся в модели BotsTelegramUserModel. Путь в модели meta.interview.[formName].

Interview

Конфиг для настройки формы, её полей и их валиацию.

bot/plugins/interview/forms - обязательный путь до форм.

Params:

Field	Type	Description
intro	String	Название формы. Название формы должно быть уникально и используется в portal-части для коннекта с формой
intro.title	String	Текст, который видит пользователь при появлении формы
intro.controls	Object	Поля формы, которые будут заполняться пользователем
controls.[name/city/age]	String	Названия полей формы внутри конфига
controls.name.title	String	Название поля формы, которое видит пользователь в `intro.title`
controls.name.placeholder	String	Текст, выводимый перед заполнением поля формы
controls.name.format	Func	Валидация входных данных
intro.fields	Array of String	Массив с активными полями формы

Example:

bots: {
  plugins: {
    interview: {
      forms: {
        intro:  {
          title: 'Добро пожаловать. Для продолжения пройдите краткую регистрацию!',
          controls: {
            name: {
              title: 'Имя',
              placeholder: 'Введите имя',
              format: String,
            },
            city: {
              title: 'Город',
              placeholder: 'Введите город',
            },
            age: {
              title: 'Возраст',
              placeholder: 'Введите ваш возраст',
              format: Number,
            },
          },
          fields: ['name', 'city', 'age'],
        },
      },
    },
  },
},

Portal

см. Bost Plugin Portal - checkInterview & replyInterview.

📖 License

This project is licensed under the MIT License - see the LICENSE file for details

👥 Contributors

_{Igor Suvorov}
💻 🎨 🤔

👏 Contributing

Fork it (https://github.com/yourname/yourproject/fork)
Create your feature branch (git checkout -b features/fooBar)
Commit your changes (git commit -am 'feat(image): Add some fooBar')
Push to the branch (git push origin feature/fooBar)
Create a new Pull Request

📮 Any questions? Always welcome :)

@lskjs/bots

Usage no npm install needed!

README

LSK.js – bots

Table of contents

⌨️ Install

Bots Plugin Portal

Правила (rules)

`cron`

`criteria`

`action`

Параметры, используемые при настройке критериев:

Список действий, которые реализованы в плагине:

createMessage

messageAppend

messageTrim

messageEditExtra

messageAddExtra

sendMessage

reply

repost

copyMessage

remove

findMessage

pinChatMessage

messageSplit

messagesJoin

checkInterview

replyInterview

Bots Plugin Interview

Interview

Portal

📖 License

👥 Contributors

👏 Contributing

📮 Any questions? Always welcome :)