---
url: /commands/arguments.md
description: >-
  Как читать аргументы пользовательской команды — слова после команды,
  упомянутого участника, срок и причину.
---

# Аргументы команды

<p class="lead">Аргументы — это все, что участник написал после команды. В <code>!выдать @anna 100 за турнир</code> аргументы — это <code>@anna</code>, <code>100</code>, <code>за</code> и <code>турнир</code>. Шаблон получает их в переменной <code>arguments</code>.</p>

## Слова по номерам { #get }

Бот делит текст после команды на слова по пробелам и нумерует их с единицы.

Пусть участник написал:

```text
!выдать @anna 100 за турнир
```

| Запись | Результат | Что это |
|---|---|---|
| `arguments.get(1)` | `@anna` | Первое слово |
| `arguments.get(2)` | `100` | Второе слово |
| `arguments.get(5)` | пусто | Такого слова нет |
| `arguments.after(3)` | `за турнир` | Все, начиная с третьего слова |
| `arguments.before(2)` | `@anna 100` | Все до второго слова включительно |
| `arguments.range(2, 3)` | `100 за` | Со второго по третье |
| `arguments.value` | `@anna 100 за турнир` | Все одной строкой |
| `arguments.args` | `[@anna, 100, за, турнир]` | Список слов |
| `arguments.args \| length` | `4` | Сколько слов |

::: tip Числа приходят текстом
`arguments.get(2)` — это текст «100», но бот сам превратит его в число, когда вы будете сравнивать или считать: `arguments.get(2) > 50` сработает правильно. Проверить, что написали именно число, можно так: `arguments.get(2) is number`.
:::

## Кому адресована команда { #target }

`arguments.targetMember` — участник, к которому обращена команда. Бот ищет его в таком порядке:

1. **Ответ на сообщение** — участник, на чье сообщение ответили командой. Самый надежный способ.
2. **Упоминание по имени** — когда вы выбираете человека из списка при вводе `@` и Telegram вставляет ссылку на него.
3. **Числовой ID** первым аргументом: `!профиль 123456789`.
4. **@username** — если бот уже видел этого участника в чате.

```template
{% set target = arguments.targetMember %}
{% require target returning 'Ответь командой на сообщение участника или упомяни его' %}
Профиль {{ target }}: уровень {{ target.rank.level }}
```

::: warning Почему @username не всегда находится
Telegram не дает ботам находить пользователей по username. Бот узнает username, только когда человек пишет в чат при боте. Поэтому надежнее отвечать командой на сообщение нужного участника.
:::

## Срок и причина { #duration }

Для команд в духе модерации есть готовый разбор срока и причины — как у встроенных `/mute` и `/ban`:

| Запись | Что вернет |
|---|---|
| `arguments.duration` | Срок из аргументов в миллисекундах: первое слово, похожее на срок |
| `arguments.reason` | Остаток текста — причина |

Сроки пишутся так: `30s`, `10m`, `2h`, `1d`, `1w`, `1mo`, `1y` или по-русски `10м`, `2ч`, `1д`, `1нед`, `1мес`, а также составные: `1ч30м`.

```template
{% set target = arguments.targetMember %}
{% require target returning 'Кого наказываем?' %}
{% set ms = arguments.duration ?: 3600000 %}
{{ target }} отправлен подумать на {{ duration(ms) }}.
Причина: {{ arguments.reason ?: 'не указана' }}
```

Функция `duration(ms)` превращает миллисекунды в понятный текст: «1 ч.», «30 мин.».

## Проверяем аргументы { #validate }

Всегда проверяйте, что участник написал нужное, — иначе команда выдаст непонятный результат. Удобнее всего тег `require`: если условие не выполнено, бот остановится и ответит вашим текстом.

```template
{% set target = arguments.targetMember %}
{% set amount = arguments.get(2) %}
{% require target returning 'Укажи участника: !выдать @anna 100' %}
{% require amount is number returning 'Укажи сумму числом: !выдать @anna 100' %}
{% require amount > 0 returning 'Сумма должна быть больше нуля' %}
{% set balance = target.getAttribute('coins').increment(amount) %}
{{ target }} получил {{ amount }} 🪙. Баланс: {{ balance }}
```

## Что не поддерживается { #unsupported }

В Telegram нет параметров slash-команд, поэтому `getOption` и `getOptionsByType` всегда возвращают пустое значение. Вместо них есть `duration` и `reason`.

Полный список — в справочнике [Arguments](/reference/arguments).