---
url: /commands/first-command.md
description: >-
  Пошаговая инструкция — создаем пользовательскую команду «!кубик», проверяем ее
  и добавляем аргументы и кнопку.
---

# Первая команда за 5 минут

<p class="lead">Сделаем команду «кубик»: участник пишет <code>!кубик</code>, бот отвечает случайным числом от 1 до 6. Потом научим кубик принимать число граней и добавим кнопку «Бросить еще».</p>

## Создаем команду { #create }

<div class="steps">

### Откройте раздел «Команды»

В панели выберите чат, в меню слева — **«Команды»**, затем вкладку **«Пользовательские»** и нажмите **«+ Создать команду»**.

### Заполните основное

| Поле | Что написать | Зачем |
|---|---|---|
| Имя | `dice` | Латиницей. По нему команда вызывается через слэш: `/dice` |
| Slash-команда | включить | Команда появится в меню Telegram |
| Алиасы | `кубик`, `кость` | Можно вызывать `!кубик` и `!кость` |
| Описание | Бросить кубик | Показывается в меню Telegram и в `/help` |
| Группа | Игры | Для порядка в списке команд |

### Настройте действие

У новой команды уже есть одно действие — оно выполняется, когда участник пишет команду. Назовите его «Бросок», тип оставьте **«Отправка сообщения»** и напишите шаблон:

```template
🎲 {{ member }} бросает кубик… выпало **{{ random(1, 6) }}**!
```

`random(1, 6)` — функция, которая выдает случайное целое число от 1 до 6 включительно.

### Сохраните

Нажмите **«Сохранить»** или <kbd>Ctrl</kbd> + <kbd>S</kbd>. Рядом с командой появится статус «Работает».

### Проверьте

Откройте вкладку **«Тест»** и нажмите **«Запустить»** — бот выполнит команду от вашего имени и пришлет результат в личные сообщения. Если бот не пишет, откройте его в Telegram и нажмите **«Запустить»** (Start): Telegram не разрешает ботам писать первыми.

Теперь напишите в чат `!кубик`:

</div>

<TgPreview user="!кубик" user-name="Анна">

🎲 [Анна](#) бросает кубик… выпало **4**!

</TgPreview>

Готово — у вас есть своя команда.

## Кубик с любым числом граней { #arguments }

Пусть участник сам выбирает, сколько граней у кубика: `!кубик 20`. Все, что написано после команды, бот передает в `arguments`, а первое слово берется так: `arguments.get(1)`.

```template
{% set sides = arguments.get(1) ?: 6 %}
{% require sides is number returning 'Напиши число граней, например: !кубик 20' %}
{% require sides >= 2 and sides <= 1000 returning 'У кубика может быть от 2 до 1000 граней' %}
🎲 {{ member }} бросает кубик на {{ sides }}… выпало **{{ random(1, sides) }}**!
```

Построчно:

1. `set sides = …` — запомнить число граней. `?: 6` значит «а если ничего не написали, то 6».
2. `require … returning '…'` — «потребовать». Если условие не выполнено, бот остановится и ответит текстом после `returning`. Здесь проверяем, что написали число.
3. Вторая проверка — что число в разумных пределах.
4. Сам ответ.

<TgPreview user="!кубик 20" user-name="Анна">

🎲 [Анна](#) бросает кубик на 20… выпало **17**!

</TgPreview>

<TgPreview user="!кубик много" user-name="Анна" label="Если написать не число">

Напиши число граней, например: !кубик 20

</TgPreview>

## Кнопка «Бросить еще» { #button }

Добавим под ответом кнопку, которая бросает кубик еще раз. Кнопка запустит то же самое действие — для этого вместо адреса действия пишем `'self'`.

```template
{% set sides = parameters.get('sides') ?: arguments.get(1) ?: 6 %}
{% require sides is number returning 'Напиши число граней, например: !кубик 20' %}
{% do parameters.store('sides', sides) %}
🎲 {{ member }} бросает кубик на {{ sides }}… выпало **{{ random(1, sides) }}**!
{% do button('PRIMARY', 'reroll', 'Бросить еще', '🎲', 'self') %}
```

Что изменилось:

* `parameters.store('sides', sides)` — бот запоминает число граней **вместе с отправленным сообщением**. Когда кто-то нажмет кнопку под ним, действие получит это число через `parameters.get('sides')`.
* `button('PRIMARY', 'reroll', 'Бросить еще', '🎲', 'self')` — синяя кнопка. По порядку: стиль, идентификатор кнопки (придумываете сами), надпись, эмодзи, какое действие запустить.

<TgPreview user="!кубик 20" user-name="Анна" :buttons="[['🎲 Бросить еще|primary']]">

🎲 [Анна](#) бросает кубик на 20… выпало **17**!

</TgPreview>

Каждое нажатие отправит новый бросок от имени того, кто нажал. Если хотите, чтобы вместо нового сообщения менялось старое, включите у действия флажок **«Заменять сообщение с нажатой кнопкой»**.

## Защита от спама { #cooldown }

Чтобы кубик не бросали сто раз в минуту, откройте вкладку **«Поля вызова»** и задайте **кулдаун**: например, 10 секунд на участника. Там же можно ограничить, кто может вызывать команду и в каких топиках. Подробнее — в статье [Настройки команды](./settings#invocation).

## Что дальше { #next }

* [Настройки команды](./settings) — все поля и права доступа.
* [Действия](./actions/) — формы, выдача ролей и другие типы.
* [Кнопки и меню выбора](./components) — цветные кнопки, листание страниц, меню.
* [Полезные примеры](/templates/examples) — готовые команды, которые можно скопировать.