Пользовательские команды
Пользовательская команда — это команда, которую вы придумали сами. Участник пишет в чат !кубик, а бот бросает кубик. Пишет !анкета — бот задает вопросы и отправляет ответы модераторам. Пишет !топ — бот показывает таблицу лидеров с кнопками «вперед» и «назад».
Команды создаются в панели: раздел «Команды» → вкладка «Пользовательские» → кнопка «+ Создать команду». Права доступа, кулдауны и остальные настройки работают так же, как у встроенных команд бота.
Сразу к практике
Если хочется сначала попробовать, а потом читать, — откройте Первая команда за 5 минут.
Как участник вызывает команду
У каждой команды есть имя латиницей и алиасы на любом языке. Вызвать команду можно двумя способами:
| Способ | Пример | Особенности |
|---|---|---|
| Через слэш | /dice | Только латиница. Если включить «Slash-команда», команда появится в меню Telegram — участник увидит ее, нажав / |
| Через префикс и алиас | !кубик, .кубик | Любой язык. Префиксы задаются в разделе «Общие», по умолчанию это ! и . |
После команды можно написать аргументы — дополнительные слова: !кубик 20, !профиль @anna. Шаблон получает их в переменной arguments — подробнее в статье Аргументы команды.
Из чего состоит команда
Команда «кубик»
├─ Настройки: имя, алиасы, описание, права, кулдаун
└─ Действия (от 1 до 10)
├─ «Бросок» (по умолчанию) — отправить сообщение с результатом
└─ «Перебросить» — запускается кнопкой под сообщением- Команда — то, что вызывает участник. У нее есть настройки: кто может вызывать, как часто, где.
- Действие — то, что делает бот. У команды может быть до 10 действий, одно из них — действие по умолчанию: оно выполняется, когда участник пишет команду. Остальные действия запускаются кнопками, формой или другим действием через
run. - Шаблон — текст или код внутри действия. Именно в нем живут
{{ }}и{% %}.
Типы действий
| Тип | Что делает бот | Пример |
|---|---|---|
| Отправка сообщения | Отправляет сообщение по шаблону, с кнопками, медиа или опросом | Кубик, профиль, топ |
| Форма | Задает участнику вопросы по очереди и передает ответы другому действию | Анкета, заявка, обратная связь |
| Изменение ролей | Выдает или снимает роли бота | «Получить роль по кнопке» |
| Встроенная команда | Вызывает встроенную команду бота | !заткнуть → /mute |
| Выполнение кода | Только выполняет шаблон: запоминает данные, выбирает следующее действие | Начислить монеты, маршрутизация |
Что умеют команды
!выдать @anna 100.Кнопки и менюЦветные кнопки, листание страниц, выбор варианта из списка.Запоминать данныеБалансы, счетчики, анкеты, топы — данные сохраняются между вызовами.Цепочки действийОдно действие запускает другое и передает ему данные.Данные AstralПрофиль игрока, клуб, рейтинги и проверка по черному списку.Общие шаблоныОдин кусок кода для многих команд — правится в одном месте.Статус проверки
Каждый раз, когда вы сохраняете команду, бот проверяет все ее шаблоны. В списке команд рядом с каждой стоит статус:
| Статус | Что значит |
|---|---|
| ● Работает | Шаблоны без ошибок, команда готова |
| ● Есть ошибки | Хотя бы в одном шаблоне ошибка. Бот не выполняет сломанные действия. Подробности — во вкладке «Диагностика» |
| ● Не проверена | Бот был недоступен в момент сохранения. Проверка пройдет, когда он снова будет на связи |
Ограничения
| Что | Сколько |
|---|---|
| Пользовательских команд в чате | до 100 |
| Команд в меню Telegram (вместе со встроенными) | до 100 |
| Действий в одной команде | до 10 |
| Алиасов у команды | до 10 |
| Кнопок под сообщением | до 25 |
| Длина шаблона | до 16 КБ |
| Вызовов всех пользовательских команд | до 30 в минуту на чат и до 5 в минуту на участника |
Лимиты самого шаблона — сколько раз можно повторить цикл, сколько данных сохранить — описаны в статье Квоты и ограничения.
Скоро: триггеры
Сейчас команду вызывает участник. Позже появятся триггеры: запуск команды по ключевому слову в сообщении, по вступлению в чат и по расписанию.