`, ``, ``, ``. Остальные теги удаляются, а их текст остаётся — например, списки (``, `- `) превращаются в обычные строки.
Ограничения длины:
* **4096** символов — обычное сообщение.
* **1024** символа — когда у шага есть вложения и `settings.attach_file` равен `true` (текст отправляется как подпись к медиа). С `attach_file: false` (по умолчанию) текст идёт отдельным сообщением после медиа, и действует лимит 4096.
* **300** символов — `poll` и `quiz` (вопрос).
### Вложения
`telegram_file_ids` принимает ID из [шага 2](#2-загрузите-файлы). Несколько вложений отправляются вместе альбомом. Переданный набор **заменяет** вложения шага; чтобы убрать один файл, используйте [Удалить вложение шага](/ru/api-reference/products/steps/delete-attachment).
### Вопросы
```json theme={null}
{
"type": "question",
"name": "How many corners does a square have?",
"text": "
Count the corners together and type the answer as a number 👇
",
"settings": {"subtype": "number", "question_error_message": "Type a number, for example: 2"},
"sending_time": {"option": "stop"}
}
```
`subtype` — одно из `text`, `number`, `email`, `phone`, `name`. Ответ проверяется по нему; при неверном формате подписчик получает `question_error_message` и может попробовать снова. Если его не задать, используется стандартное сообщение на языке бота. `save_profile: true` сохраняет ответ `name`, `email` или `phone` в профиль подписчика.
### Опросы и квизы
```json theme={null}
{
"type": "quiz",
"name": "Quiz: triangle corners",
"text": "How many corners does a triangle have?
",
"options": [{"text": "2"}, {"text": "3", "is_correct": true}, {"text": "4"}],
"settings": {"quiz_explanation": "Tri-angle — three corners!"},
"sending_time": {"option": "stop"}
}
```
* 2–12 вариантов, каждый до 100 символов.
* У `quiz` должен быть **ровно один** `is_correct: true`, иначе `422` `options`.
* `quiz_explanation` (до 200 символов) показывается после ответа.
* У `poll` нет правильного ответа.
### Задания
```json theme={null}
{
"type": "task",
"name": "Assignment 1. Shape hunt",
"text": "Find 3 round and 3 square things at home, put them together, and take a photo. Press the button below and send the photo.
",
"task_autocheck": true,
"sending_time": {"option": "stop"}
}
```
Кнопка сдачи создаётся автоматически с названием на языке бота — не добавляйте её сами. Подписчик нажимает её и отправляет работу в чат.
* `task_autocheck: true` — задание принимается при сдаче, и курс сразу идёт дальше.
* `task_autocheck: false` — задание ждёт проверки в [Список заданий](/ru/api-reference/tasks/list); курс продолжится после того, как вы [примете его](/ru/api-reference/tasks/approve).
## 4. Настройте, когда отправляется каждый шаг
У каждого шага есть `sending_time`. Шаг планируется, когда отправлен предыдущий; первый шаг — когда подписчик получает доступ к продукту. Когда именно, решает `sending_time.option`:
| `option` | Шаг отправляется | Поля |
| - | - | - |
| `immediately` | сразу после предыдущего шага | — |
| `stop` | после действия подписчика на предыдущем шаге | — |
| `duration` | через заданное время | `delay_number`, `delay_type`, необязательно `delay_limit` |
| `time` | в заданное время суток | `delay_time`, необязательно `delay_number`, `delay_limit` |
| `date` | в точную дату и время | `delay_at`, необязательно `skip_past_date` |
| `never` | не отправляется автоматически | — |
Задайте его при создании шага или позже через [Обновить время отправки](/ru/api-reference/products/steps/update-sending-time):
```bash theme={null}
curl -X PATCH $API/products/$PRODUCT_ID/steps/$NEXT_STEP_ID/sending-time \
-H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
-d '{"sending_time": {"option": "stop"}}'
```
Подписчика ждёт только `stop`. С любым другим вариантом следующий шаг планируется сразу после отправки предыдущего — даже если подписчик ещё не ответил на вопрос и не сдал задание. Если у всех шагов `immediately`, весь курс придёт сразу.
### Ждать подписчика: `stop`
Что считается действием на предыдущем шаге:
| Предыдущий шаг | Следующий шаг со `stop` отправляется, когда подписчик… |
| - | - |
| `question`, `quiz`, `poll` | отвечает |
| `task` | сдаёт задание (с `task_autocheck`) или вы его принимаете |
| любой шаг с кнопкой `send_next_step` | нажимает кнопку |
У `message` и `lesson` своего действия нет — добавьте им кнопку:
```bash theme={null}
curl -X POST $API/products/$PRODUCT_ID/steps/$LESSON_STEP_ID/buttons \
-H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
-d '{"type": "action", "name": "✅ Watched! Next", "actions": [{"name": "send_next_step"}]}'
```
`stop` принимается, только если у предыдущего шага уже есть действие. Иначе запрос завершится ошибкой `422` `sending_time` — «Select the action in the previous step». Первый шаг продукта не может быть `stop`.
Поэтому порядок важен. Либо:
* создавайте шаги по одному: после каждого `message` или `lesson` добавьте ему кнопку, затем создайте следующий шаг со `stop`; либо
* создайте все шаги с `immediately`, добавьте кнопки, затем переключите шаги 2…N на `stop` через [Обновить время отправки](/ru/api-reference/products/steps/update-sending-time).
Типичный курс:
| # | Шаг | `sending_time` | Идёт дальше, когда |
| - | - | - | - |
| 1 | `message` Приветствие + кнопка «🚀 Начать» | `immediately` | кнопка |
| 2 | `question` (`name`) Знакомство | `stop` | ответ |
| 3 | `lesson` Урок 1 + кнопка «Дальше» | `stop` | кнопка |
| 4 | `quiz` | `stop` | ответ |
| 5 | `message` Материалы для печати + кнопка «Дальше» | `stop` | кнопка |
| 6 | `task` Задание (`task_autocheck`) | `stop` | сдача |
| 7 | `poll` Любимая фигура | `stop` | ответ |
| 8 | `message` Сертификат | `stop` | — |
### Через время: `duration`
```json theme={null}
{"option": "duration", "delay_number": 1, "delay_type": "days"}
```
Задержка отсчитывается от момента отправки предыдущего шага, а для первого шага — от момента получения доступа. `delay_type` — `seconds`, `minutes`, `hours` или `days`.
После текстового `question` есть одно исключение: если подписчик отвечает до окончания задержки, отсчёт начинается заново с момента ответа. Ответы на опросы и квизы и сданные задания на задержку не влияют.
Чтобы сообщения не приходили ночью или в выходные, добавьте окно отправки (`delay_limit`, см. ниже).
### В заданное время суток: `time`
```json theme={null}
{"option": "time", "delay_time": "2026-01-01T10:00:00+02:00", "delay_number": 1}
```
* Из `delay_time` берётся только **время суток**, дата игнорируется. Передавайте его со смещением — см. [Часовой пояс](#часовой-пояс).
* `delay_number` — через сколько дней после отправки предыдущего шага: `0` — в тот же день в это время или на следующий день, если это время уже прошло; `1` — на следующий день; и так далее.
* `delay_limit.weekdays` ограничивает дни: в неразрешённый день шаг переносится на ближайший разрешённый день в то же время. `time_from` и `time_to` для этого варианта игнорируются.
Например, «каждый урок на следующее утро в 10:00» — это `time` с `delay_number: 1` на каждом уроке.
### В дату: `date`
```json theme={null}
{"option": "date", "delay_at": "2026-11-01T10:00:00+02:00", "skip_past_date": false}
```
Шаг отправляется всем подписчикам в один и тот же момент — используйте это для запусков и живых событий. Передавайте `delay_at` со смещением — см. [Часовой пояс](#часовой-пояс).
* При сохранении активного шага `delay_at` должен быть в будущем, иначе `422` `sending_time` — «Change the sending time to a date in the future».
* Подписчик, который дошёл до шага после этой даты, получает его сразу. С `skip_past_date: true` шаг вместо этого пропускается, и подписчик переходит к следующему.
### Окно отправки: `delay_limit`
Ограничивает `duration` определёнными часами и днями (для `time` применяются только дни):
```json theme={null}
{
"option": "duration", "delay_number": 2, "delay_type": "hours",
"delay_limit": {"time_from": 540, "time_to": 1260, "weekdays": ["mon", "tue", "wed", "thu", "fri"]}
}
```
* `time_from` и `time_to` — минуты от полуночи в [часовом поясе проекта](#часовой-пояс): `540` — это 09:00, `1260` — 21:00. Учитываются только целые часы: `570` (09:30) работает как 09:00.
* `time_from` больше `time_to` — ночное окно, например `1320`–`360` (22:00–06:00).
* `time_from`, равный `time_to`, означает любое время суток; тогда действуют только `weekdays`.
* `weekdays`: `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun` — хотя бы один.
* Если шаг выпадает за пределы окна, он переносится на ближайший момент, когда окно открыто в разрешённый день.
* Окно «любое время во все семь дней» равнозначно отсутствию окна и не сохраняется.
### Не отправлять автоматически: `never`
Шаг в курсе пропускается: подписчики не получают его после предыдущего шага, и следующий шаг идёт сразу за предыдущим. Это значение по умолчанию, если `sending_time` не передан.
### Часовой пояс
Расписание считается в часовом поясе вашего проекта (в личном кабинете: **Настройки → Проект → Основное → Часовой пояс**; если не задан — UTC): время суток для `time`, а также часы и дни `delay_limit`.
`delay_at` и `delay_time` — значения даты и времени. Значение без смещения читается как UTC, поэтому передавайте смещение часового пояса проекта — например, `10:00:00+02:00` для 10:00 по Киеву зимой. Для `time` время суток остаётся фиксированным в часовом поясе проекта круглый год.
## 5. Включите продукт
```bash theme={null}
curl -X PUT $API/products/$PRODUCT_ID/active \
-H "Authorization: Bearer $TOKEN" -H "Accept: application/json"
```
Когда продукт включён, выдайте подписчикам доступ — см. [Выдать доступ к продукту](/ru/guides/product-access).
## Что нужно помнить
* **Язык стандартных текстов.** Кнопка задания, её сообщения и стандартные ошибки вопросов создаются на **языке бота**. Ответы API и сообщения об ошибках всегда на английском.
* **Файлы привязаны к пользователю.** Файлы, зарегистрированные с одним API-токеном, нельзя прикрепить токеном другого пользователя.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.