---
url: /commands.md
description: >-
  Пользовательские команды Astral Moderation — свои команды для Telegram-чата с
  ответами, кнопками, формами, ролями и хранением данных.
---

# Пользовательские команды

<p class="lead">Пользовательская команда — это команда, которую вы придумали сами. Участник пишет в чат <code>!кубик</code>, а бот бросает кубик. Пишет <code>!анкета</code> — бот задает вопросы и отправляет ответы модераторам. Пишет <code>!топ</code> — бот показывает таблицу лидеров с кнопками «вперед» и «назад».</p>

Команды создаются в панели: раздел **«Команды»** → вкладка **«Пользовательские»** → кнопка **«+ Создать команду»**. Права доступа, кулдауны и остальные настройки работают так же, как у встроенных команд бота.

::: tip Сразу к практике
Если хочется сначала попробовать, а потом читать, — откройте [Первая команда за 5 минут](./first-command).
:::

## Как участник вызывает команду { #invoke }

У каждой команды есть **имя** латиницей и **алиасы** на любом языке. Вызвать команду можно двумя способами:

| Способ | Пример | Особенности |
|---|---|---|
| Через слэш | `/dice` | Только латиница. Если включить «Slash-команда», команда появится в меню Telegram — участник увидит ее, нажав `/` |
| Через префикс и алиас | `!кубик`, `.кубик` | Любой язык. Префиксы задаются в разделе **«Общие»**, по умолчанию это `!` и `.` |

После команды можно написать **аргументы** — дополнительные слова: `!кубик 20`, `!профиль @anna`. Шаблон получает их в переменной `arguments` — подробнее в статье [Аргументы команды](./arguments).

## Из чего состоит команда { #anatomy }

```text
Команда «кубик»
├─ Настройки: имя, алиасы, описание, права, кулдаун
└─ Действия (от 1 до 10)
   ├─ «Бросок» (по умолчанию) — отправить сообщение с результатом
   └─ «Перебросить» — запускается кнопкой под сообщением
```

* **Команда** — то, что вызывает участник. У нее есть [настройки](./settings): кто может вызывать, как часто, где.
* **Действие** — то, что делает бот. У команды может быть до 10 действий, одно из них — **действие по умолчанию**: оно выполняется, когда участник пишет команду. Остальные действия запускаются [кнопками](./components), [формой](./actions/form) или другим действием через [`run`](./run).
* **Шаблон** — текст или код внутри действия. Именно в нем живут `{{ }}` и `{% %}`.

## Типы действий { #action-types }

| Тип | Что делает бот | Пример |
|---|---|---|
| [Отправка сообщения](./actions/message) | Отправляет сообщение по шаблону, с кнопками, медиа или опросом | Кубик, профиль, топ |
| [Форма](./actions/form) | Задает участнику вопросы по очереди и передает ответы другому действию | Анкета, заявка, обратная связь |
| [Изменение ролей](./actions/change-roles) | Выдает или снимает роли бота | «Получить роль по кнопке» |
| [Встроенная команда](./actions/internal) | Вызывает встроенную команду бота | `!заткнуть` → `/mute` |
| [Выполнение кода](./actions/code) | Только выполняет шаблон: запоминает данные, выбирает следующее действие | Начислить монеты, маршрутизация |

## Что умеют команды { #features }

<div class="cards">
  <a class="card" href="/commands/arguments">
    <span class="card-title">Читать аргументы</span>
    <span class="card-text">Узнать, кого упомянули, на какой срок и за что: <code>!выдать @anna 100</code>.</span>
  </a>
  <a class="card" href="/commands/components">
    <span class="card-title">Кнопки и меню</span>
    <span class="card-text">Цветные кнопки, листание страниц, выбор варианта из списка.</span>
  </a>
  <a class="card" href="/templates/storage/attributes">
    <span class="card-title">Запоминать данные</span>
    <span class="card-text">Балансы, счетчики, анкеты, топы — данные сохраняются между вызовами.</span>
  </a>
  <a class="card" href="/commands/run">
    <span class="card-title">Цепочки действий</span>
    <span class="card-text">Одно действие запускает другое и передает ему данные.</span>
  </a>
  <a class="card" href="/templates/astral">
    <span class="card-title">Данные Astral</span>
    <span class="card-text">Профиль игрока, клуб, рейтинги и проверка по черному списку.</span>
  </a>
  <a class="card" href="/templates/shared">
    <span class="card-title">Общие шаблоны</span>
    <span class="card-text">Один кусок кода для многих команд — правится в одном месте.</span>
  </a>
</div>

## Статус проверки { #compile-status }

Каждый раз, когда вы сохраняете команду, бот проверяет все ее шаблоны. В списке команд рядом с каждой стоит статус:

| Статус | Что значит |
|---|---|
| ● Работает | Шаблоны без ошибок, команда готова |
| ● Есть ошибки | Хотя бы в одном шаблоне ошибка. Бот не выполняет сломанные действия. Подробности — во вкладке **«Диагностика»** |
| ● Не проверена | Бот был недоступен в момент сохранения. Проверка пройдет, когда он снова будет на связи |

## Ограничения { #limits }

| Что | Сколько |
|---|---|
| Пользовательских команд в чате | до 100 |
| Команд в меню Telegram (вместе со встроенными) | до 100 |
| Действий в одной команде | до 10 |
| Алиасов у команды | до 10 |
| Кнопок под сообщением | до 25 |
| Длина шаблона | до 16 КБ |
| Вызовов всех пользовательских команд | до 30 в минуту на чат и до 5 в минуту на участника |

Лимиты самого шаблона — сколько раз можно повторить цикл, сколько данных сохранить — описаны в статье [Квоты и ограничения](/templates/advanced/limits).

::: info Скоро: триггеры
Сейчас команду вызывает участник. Позже появятся триггеры: запуск команды по ключевому слову в сообщении, по вступлению в чат и по расписанию.
:::