`, ``, ``, ``. Інші теги видаляються, а їхній текст залишається — наприклад, списки (``, `- `) перетворюються на звичайні рядки.
Обмеження довжини:
* **4096** символів — звичайне повідомлення.
* **1024** символи — коли в кроку є вкладення і `settings.attach_file` дорівнює `true` (текст надсилається як підпис до медіа). З `attach_file: false` (за замовчуванням) текст іде окремим повідомленням після медіа, і діє ліміт 4096.
* **300** символів — `poll` і `quiz` (запитання).
### Вкладення
`telegram_file_ids` приймає ID з [кроку 2](#2-завантажте-файли). Кілька вкладень надсилаються разом альбомом. Переданий набір **замінює** вкладення кроку; щоб прибрати один файл, використовуйте [Видалити вкладення кроку](/uk/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` — завдання чекає на перевірку в [Список завдань](/uk/api-reference/tasks/list); курс продовжиться після того, як ви [приймете його](/uk/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` | не надсилається автоматично | — |
Задайте його під час створення кроку або пізніше через [Оновити час надсилання](/uk/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` через [Оновити час надсилання](/uk/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"
```
Коли продукт увімкнений, видайте підписникам доступ — див. [Видати доступ до продукту](/uk/guides/product-access).
## Що потрібно пам’ятати
* **Мова стандартних текстів.** Кнопка завдання, її повідомлення та стандартні помилки запитань створюються **мовою бота**. Відповіді API й повідомлення про помилки завжди англійською.
* **Файли прив’язані до користувача.** Файли, зареєстровані з одним API-токеном, не можна прикріпити токеном іншого користувача.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.