Документация API

REST API для уведомлений через Telegram и Max. Подписчики, OTP, рассылки, формы, helpdesk.

POST /v1/send

Отправка персонального уведомления конкретному подписчику.

Параметры

subscriber_id string (UUID)

UUID подписчика (из списка подписчиков)

text string

Текст сообщения (до 4000 символов). Обязателен, если не указан template

format string

Формат текста: plain (по умолчанию), markdown или html

media object

Объект медиа: {type, url}. Типы: photo, video, document

buttons array

Массив рядов кнопок: [[{text, url}]] или [[{text, callback_data}]]

template string

Slug шаблона вместо text

vars object

Переменные для шаблона: {key: value}

permission string

Фильтр по разрешению: отправить только подписчикам с этим ключом

segment string

Фильтр по сегменту (тегу)

Пример запроса

POST /v1/send
 
{
"subscriber_id": "550e8400-e29b-41d4-a716-446655440000",
"text": "Заказ #1042 отправлен!",
"format": "markdown",
"buttons": [[{
"text": "Отследить",
"url": "https://example.com/track/1042"
}]]
}

Ответ

{
"ok": true,
"message_id": "msg_abc123"
}

Шаблоны

Шаблоны позволяют переиспользовать текст с переменными. Создаются в дашборде или через API.

Использование: передайте template и vars вместо text в /v1/send.

Переменные в шаблоне обозначаются {{имя}}. Например: «Заказ {{order_id}} доставлен».

POST /v1/send
 
{
"subscriber_id": "550e8400-e29b-41d4-a716-446655440000",
"template": "order_delivered",
"vars": {
"order_id": "1042",
"customer": "Иван"
}
}

Медиа и кнопки

К уведомлениям можно прикрепить медиа-файлы и inline-кнопки.

Типы медиа: photo, video, document. Передайте URL файла.

Кнопки — двумерный массив: внешний массив — ряды, внутренний — кнопки в ряду.

  • Кнопка с URL: {"text": "Открыть", "url": "https://..."}
  • Кнопка с callback: {"text": "Да", "callback_data": "confirm_123"}
POST /v1/send
 
{
"subscriber_id": "550e8400-e29b-41d4-a716-446655440000",
"text": "Ваш заказ готов",
"media": {
"type": "photo",
"url": "https://example.com/photo.jpg"
},
"buttons": [[
{"text": "Подробнее", "url": "https://..."},
{"text": "Отмена", "callback_data": "cancel_123"}
]]
}

1 медиа + кнопки — поддерживается. Несколько медиа + кнопки — не поддерживается (ограничение Telegram). Caption с медиа: до 1024 символов (Telegram) / до 4000 (Max). Текст без медиа — до 4000 символов.

Связанные разделы

Быстрый старт
Первое сообщение за 2 минуты: получение ключа, deep link для подписки, отправка через curl.
Аутентификация
Как авторизовать запросы к API через Authorization: Bearer zn_… ключ проекта.
OTP — коды подтверждения
Генерация и проверка 6-значных кодов. Отдельный flow для пользователей без подписки.