`, ``, ``, ``. Any other tag is stripped and its text is kept — for example, lists (``, `- `) turn into plain lines.
Length limits:
* **4096** characters — a regular message.
* **1024** characters — when the step has attachments and `settings.attach_file` is `true` (the text is sent as the media caption). With `attach_file: false` (the default), the text goes as a separate message after the media, and the 4096 limit applies.
* **300** characters — `poll` and `quiz` (the question).
### Attachments
`telegram_file_ids` takes IDs from [step 2](#2-upload-files). Several attachments are sent together as an album. The set you pass **replaces** the step's attachments; to remove one file use [Delete step attachment](/api-reference/products/steps/delete-attachment).
### Questions
```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` is one of `text`, `number`, `email`, `phone`, `name`. The answer is checked against it; on a wrong format the subscriber gets `question_error_message` and can try again. If you don't set it, a default message in the bot's language is used. `save_profile: true` saves a `name`, `email`, or `phone` answer to the subscriber's profile.
### Polls and quizzes
```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 options, up to 100 characters each.
* A `quiz` needs **exactly one** `is_correct: true`, otherwise `422` `options`.
* `quiz_explanation` (up to 200 characters) is shown after the answer.
* A `poll` has no correct answer.
### Assignments
```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"}
}
```
The submission button is created automatically, named in the bot's language — don't add it yourself. The subscriber presses it and sends their work to the chat.
* `task_autocheck: true` — the assignment is accepted on submission, and the course continues right away.
* `task_autocheck: false` — the assignment waits for review in [Assignments](/api-reference/tasks/list); the course continues after you [approve it](/api-reference/tasks/approve).
## 4. Set when each step is sent
Every step has a `sending_time`. A step is scheduled when the previous step is sent; the first step — when the subscriber gets access to the product. `sending_time.option` decides when exactly:
| `option` | The step is sent | Fields |
| - | - | - |
| `immediately` | right after the previous step | — |
| `stop` | after the subscriber's action on the previous step | — |
| `duration` | after a delay | `delay_number`, `delay_type`, optional `delay_limit` |
| `time` | at a time of day | `delay_time`, optional `delay_number`, `delay_limit` |
| `date` | at an exact date and time | `delay_at`, optional `skip_past_date` |
| `never` | not sent automatically | — |
Set it when you create the step, or later with [Update sending time](/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"}}'
```
Only `stop` waits for the subscriber. With any other option, the next step is scheduled as soon as the previous one is sent — even if the subscriber hasn't answered the question or submitted the assignment yet. With `immediately` on every step, the whole course arrives at once.
### Wait for the subscriber: `stop`
What counts as an action on the previous step:
| Previous step | The next `stop` step is sent when the subscriber… |
| - | - |
| `question`, `quiz`, `poll` | answers |
| `task` | submits the assignment (with `task_autocheck`) or you approve it |
| any step with a `send_next_step` button | presses the button |
A `message` or `lesson` has no action of its own — give it a button:
```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` is accepted only if the previous step already has an action. Otherwise the request fails with `422` `sending_time` — "Select the action in the previous step". The first step of a product can't be `stop`.
So the order matters. Either:
* create the steps one by one: after each `message` or `lesson`, add its button, then create the next step with `stop`; or
* create all steps with `immediately`, add the buttons, then switch steps 2…N to `stop` with [Update sending time](/api-reference/products/steps/update-sending-time).
A typical course:
| # | Step | `sending_time` | Moves on when |
| - | - | - | - |
| 1 | `message` Welcome + button «🚀 Start» | `immediately` | button |
| 2 | `question` (`name`) Introductions | `stop` | answer |
| 3 | `lesson` Lesson 1 + button «Next» | `stop` | button |
| 4 | `quiz` | `stop` | answer |
| 5 | `message` Printables + button «Next» | `stop` | button |
| 6 | `task` Assignment (`task_autocheck`) | `stop` | submission |
| 7 | `poll` Favourite shape | `stop` | answer |
| 8 | `message` Certificate | `stop` | — |
### After a delay: `duration`
```json theme={null}
{"option": "duration", "delay_number": 1, "delay_type": "days"}
```
The delay counts from the moment the previous step was sent — for the first step, from the moment the subscriber got access. `delay_type` is `seconds`, `minutes`, `hours`, or `days`.
After a text `question` there's one exception: if the subscriber answers before the delay is over, the delay starts again from the moment of the answer. Answers to polls and quizzes and submitted assignments don't affect the delay.
To keep messages out of the night or weekends, add a sending window (`delay_limit`, see below).
### At a time of day: `time`
```json theme={null}
{"option": "time", "delay_time": "2026-01-01T10:00:00+02:00", "delay_number": 1}
```
* Only the **time of day** from `delay_time` is used; the date part is ignored. Pass it with an offset — see [Time zone](#time-zone).
* `delay_number` is the number of days after the previous step was sent: `0` — the same day at that time, or the next day if that time has already passed; `1` — the next day; and so on.
* `delay_limit.weekdays` limits the days: on a day that isn't allowed, the step moves to the next allowed day at the same time. `time_from` and `time_to` are ignored for this option.
For example, "every lesson the next morning at 10:00" is `time` with `delay_number: 1` on each lesson.
### On a date: `date`
```json theme={null}
{"option": "date", "delay_at": "2026-11-01T10:00:00+02:00", "skip_past_date": false}
```
The step is sent at the same moment to every subscriber — use it for launches and live events. Pass `delay_at` with an offset — see [Time zone](#time-zone).
* When you save an active step, `delay_at` must be in the future, otherwise `422` `sending_time` — "Change the sending time to a date in the future".
* A subscriber who reaches the step after the date has passed gets it right away. With `skip_past_date: true`, the step is skipped instead, and the subscriber moves on to the next step.
### Sending window: `delay_limit`
Limits `duration` to certain hours and days (for `time`, only the days apply):
```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` and `time_to` are minutes from midnight in the [workspace time zone](#time-zone): `540` is 09:00, `1260` is 21:00. Only whole hours count — `570` (09:30) works as 09:00.
* `time_from` greater than `time_to` is an overnight window, for example `1320`–`360` (22:00–06:00).
* `time_from` equal to `time_to` means any time of day; then only `weekdays` apply.
* `weekdays`: `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun` — at least one.
* If the step falls outside the window, it's moved to the next moment the window is open on an allowed day.
* A window of any time on all seven days is the same as no window and isn't saved.
### Not sent automatically: `never`
The step is skipped in the course: subscribers don't get it after the previous step, and the next step follows the previous one directly. This is the default when `sending_time` is omitted.
### Time zone
Schedules are calculated in the time zone of your workspace (**Settings → Workspace → General → Time Zone** in the dashboard; UTC if not set): the time of day for `time`, and the hours and days of `delay_limit`.
`delay_at` and `delay_time` are date-time values. A value without an offset is read as UTC, so pass the offset of your workspace time zone — for example, `10:00:00+02:00` for 10:00 in Kyiv in winter. For `time`, the time of day stays fixed in the workspace time zone all year.
## 5. Activate the product
```bash theme={null}
curl -X PUT $API/products/$PRODUCT_ID/active \
-H "Authorization: Bearer $TOKEN" -H "Accept: application/json"
```
When the product is active, give subscribers access to it — see [Give access to a product](/guides/product-access).
## Things to keep in mind
* **Language of default texts.** The assignment button, its messages, and the default question errors are created in the **bot's language**. API responses and error messages are always in English.
* **Files are per user.** Files registered with one API token can't be attached by another user's token.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.