Публичный API Widgram
API позволяет отправлять виджеты и менять их состояние из своей CRM, магазина или бота, читать статистику и заявки, получать события на свой сервер.
Ниже в примерах https://api.example.com — адрес вашей установки (API_HOST), wg_live_… — ключ.
Основы
| Адрес | https://<API_HOST>/api/v1 |
| Ключ | заголовок Authorization: Bearer wg_live_…. Выпускается в кабинете, раздел «API»; показывается один раз. В базе хранится только хэш |
| Формат | запросы и ответы — JSON в UTF-8 (Content-Type: application/json). Тело запроса — объект, не больше 256 КБ |
| Идентификаторы | виджет w_…, сообщение m_…, бот b_… — те же, что в кабинете |
| Время | ISO 8601 в UTC (2026-11-17T12:00:00Z); даты статистики — ГГГГ-ММ-ДД, сутки по UTC |
| Язык текстов ошибок | Accept-Language: ru или en, либо ?locale=en |
| Лимит | 60 запросов в секунду на ключ, общий для всех методов. Превышение — 429 с Retry-After: 1 |
Ошибки
Любая ошибка имеет один вид:
{ "error": { "code": "state_source", "message": "Это состояние строит движок виджета — снаружи его менять нельзя." } }
Опирайтесь на code и статус ответа; message — текст для человека, он может меняться.
| Статус | code |
Когда |
|---|---|---|
| 400 | invalid_json |
тело — не JSON |
| 400 | idempotency_key_invalid |
Idempotency-Key пуст, длиннее 255 символов или содержит не печатные символы ASCII |
| 401 | unauthorized |
ключа нет, он неверен или отозван |
| 402 | mau_limit |
исчерпан лимит активных пользователей тарифа |
| 403 | plan_required |
метод недоступен на тарифе аккаунта |
| 403 | moderation_required, wallet_forbidden, bot_blocked |
виджет не прошёл проверку; виджет с кошельком через системного бота; пользователь заблокировал бота |
| 404 | not_found, bot_not_found |
объекта нет или он принадлежит другому аккаунту |
| 409 | state_source |
состояние строит движок виджета — снаружи его не изменить |
| 409 | widget_inactive, widget_not_published, version_broken, message_unavailable, bot_inactive, bot_mode, bot_unauthorized, no_bot, update_in_progress, idempotency_in_progress |
объект в состоянии, в котором действие невозможно |
| 413 | payload_too_large |
тело больше 256 КБ |
| 422 | html_required, invalid_body, invalid_param, invalid_chat_id, invalid_update, caption_required, caption_too_long, chat_not_allowed, state_invalid, state_too_large, telegram_rejected, idempotency_key_reused |
неверные данные запроса |
| 429 | rate_limited, repeat, throttled, daily_limit |
слишком часто; смотрите Retry-After |
| 502 | telegram_unavailable |
Telegram не ответил; запрос можно повторить |
Идемпотентность
Все изменяющие методы (POST, PATCH) принимают заголовок Idempotency-Key — любую строку до 255 печатных символов ASCII без пробелов, например номер заказа.
- Запрос выполняется один раз. Повтор с тем же ключом и тем же телом возвращает сохранённый ответ и заголовок
Idempotent-Replayed: true. - Тот же ключ с другим запросом —
422 idempotency_key_reused. - Пока первый запрос ещё выполняется, повтор получает
409 idempotency_in_progress. - Запоминаются только успешные ответы. После ошибки ничего не изменилось, и запрос с тем же ключом выполнится заново.
- Ответ хранится 24 часа. Ключи разных аккаунтов не пересекаются.
Что доступно на каком тарифе
| Методы | С какого тарифа |
|---|---|
POST /compile |
любой, можно без ключа |
GET /widgets, GET /widgets/:id, POST /widgets/:id/send, PATCH /messages/:id/state, PATCH /widgets/:id/state |
«Старт» |
GET /widgets/:id/stats, GET /leads, POST /bots/:id/updates, исходящие вебхуки |
«Про» |
Методы
POST /compile
Проверить и сжать HTML виджета. Без ключа — 10 запросов в минуту с одного адреса; с ключом действует лимит ключа. Единственный метод, открытый для запросов из браузера с чужих сайтов (CORS).
curl -X POST https://api.example.com/api/v1/compile \
-H "Content-Type: application/json" \
-d '{"html": "<h3>Привет</h3><button>Нажми</button>"}'
Ответ: html (сжатый код), size_raw, size_zlib, ok, issues[] (замечания линтера с level, code, line, message, fix_hint), manifest, limits. Код можно прислать и телом запроса с Content-Type: text/html.
GET /widgets
Список виджетов аккаунта, новые первыми. Архивные не показываются, пока не попросить status=archived.
Параметры: status (draft, active, paused, archived), limit (1–100, по умолчанию 50), starting_after (идентификатор последнего полученного виджета).
{
"data": [
{
"id": "w_8fK2mQ9xTa",
"name": "Статус заказа",
"template": "status",
"status": "active",
"moderation_status": "approved",
"published": true,
"caption": "Ваш заказ",
"link": "https://t.me/WidgramBot?start=w_8fK2mQ9xTa",
"version": { "number": 2, "size": 1874, "shared": false, "allow_queries": false, "cache_time": null, "broken": false, "published_at": "2026-11-17T09:30:00Z" },
"state": { "public_data": null, "chat_data": "raw" },
"created_at": "2026-11-16T18:02:11Z",
"updated_at": "2026-11-17T09:30:00Z"
}
],
"has_more": false
}
Поле state говорит, кто пишет состояние: engine — его строит движок виджета (опрос, квиз, колесо), снаружи менять нельзя; raw — пишется через API как есть; null — такого состояния у виджета нет.
GET /widgets/:id
Карточка одного виджета — тот же объект.
POST /widgets/:id/send
Отправить опубликованный виджет в чат.
| Поле | Тип | |
|---|---|---|
chat_id |
число | обязательно. В личном чате это идентификатор пользователя Telegram |
bot_id |
строка | бот аккаунта (b_…). Без него — бот виджета по умолчанию, иначе системный бот |
chat_data |
строка, объект или null |
начальное состояние сообщения, до 1024 байт. Объект сериализуется в компактный JSON. Только если state.chat_data виджета — не engine |
caption |
строка | подпись вместо подписи из настроек виджета, до 1024 символов |
reply_markup |
объект | клавиатура под сообщением в формате Bot API |
disable_notification |
логическое | отправить без звука |
curl -X POST https://api.example.com/api/v1/widgets/w_8fK2mQ9xTa/send \
-H "Authorization: Bearer wg_live_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042" \
-d '{"chat_id": 111111111, "chat_data": {"s": 1}}'
Ответ 201:
{
"id": "m_Xk29LmPq7Z",
"widget": "w_8fK2mQ9xTa",
"bot": "b_4hT7vNc2Qe",
"chat_id": 111111111,
"message_id": 4521,
"chat_data": "{\"s\":1}",
"sent_at": "2026-11-17T12:00:00Z"
}
Сохраните id: по нему состояние сообщения меняется дальше.
Особые ответы: 429 repeat — этот виджет только что отправлен этому человеку, повторите через 10 секунд; 429 throttled — очередь бота занята или Telegram попросил подождать, время в Retry-After; 402 mau_limit — исчерпан лимит тарифа; 403 bot_blocked — пользователь не начинал чат с ботом или заблокировал его.
Через системного бота виджет отправляется только после проверки (moderation_status: approved) и только тем, кто сам начал чат с ботом, — так устроен Telegram.
PATCH /messages/:id/state
Изменить chat_data отправленного сообщения — например, этап заказа. :id — идентификатор из ответа на отправку.
curl -X PATCH https://api.example.com/api/v1/messages/m_Xk29LmPq7Z/state \
-H "Authorization: Bearer wg_live_…" \
-H "Content-Type: application/json" \
-d '{"chat_data": {"s": 3, "t": "Курьер выехал", "eta": 1763400000}}'
chat_data — строка, объект или null (очистить). Ответ 200 — объект сообщения с новым chat_data и полем pending: true: запись принята сразу, а до Telegram её доносит фоновый процесс, обычно за секунды. Несколько записей подряд сливаются — до Telegram доходит последняя.
409 state_source — состояние этого сообщения строит движок виджета. 409 message_unavailable — сообщение не было отправлено, удалено или бот заблокирован.
PATCH /widgets/:id/state
Изменить общее состояние виджета — то, что видят все его получатели.
Вариант 1 — public_data целиком, для виджетов с state.public_data: "raw":
{ "public_data": { "price": 990, "left": 3 } }
Вариант 2 — отдельные поля, которые шаблон объявил изменяемыми (сейчас это дата окончания у таймера и розыгрыша):
{ "fields": { "end": 1767225600 } }
В запросе должен быть ровно один из двух ключей. Ответ 200: { "id": "w_…", "revision": 7, "public_data": "…" } — номер ревизии и текст, который получат виджеты. 409 state_source — у виджета это состояние строит движок либо поле менять нельзя.
POST /bots/:id/updates
Для бота в режиме send_only — когда вебхук бота остаётся у вашего сервера. Чтобы в таком боте работали кнопки виджетов, пересылайте нам его обновления: тело запроса — обновление Telegram как есть.
{ "handled": true, "outcome": "processed" }
handled |
outcome |
Что это значит |
|---|---|---|
true |
processed |
это запрос нашего виджета; мы ответили на него сами |
true |
duplicate |
это обновление мы уже обработали |
false |
foreign |
не наше — обрабатывайте сами |
Наши — только widget_query и shared_widget_query по виджетам, которые отправили мы. Пересылать можно все обновления подряд или только эти два типа. 409 bot_mode — бот подключён в другом режиме, его обновления мы получаем сами.
Бот подключается в кабинете, в разделе «Боты», в режиме «Только отправка»; его идентификатор (b_…) показан на странице бота.
GET /widgets/:id/stats
Статистика виджета по дням. Параметры from и to (ГГГГ-ММ-ДД); по умолчанию последние 30 дней, не больше 366.
{
"widget": "w_8fK2mQ9xTa",
"from": "2026-10-19",
"to": "2026-11-17",
"totals": { "sent": 120, "views": 96, "actions": 210, "leads": 4, "link_clicks": 0, "unique_users": 101 },
"days": [ { "date": "2026-11-17", "sent": 12, "views": 9, "actions": 31, "leads": 1, "link_clicks": 0, "unique_users": 14 } ],
"actions": { "vote": 210 },
"distribution": [ { "label": "Кофе", "value": 130 }, { "label": "Чай", "value": 80 } ]
}
unique_users в totals — сумма по дням, а не число разных людей за период. distribution есть у опроса и оценки, у остальных — null. Показы считаются только у виджетов с разрешёнными запросами.
GET /leads
Заявки, новые первыми. Параметры: widget (w_…), status (new, in_progress, done, spam), limit (1–100), starting_after (id последней полученной заявки).
{
"data": [
{
"id": 381,
"widget": "w_Qm3xL8rT2a",
"status": "new",
"user": { "id": 111111111, "first_name": "Анна", "username": "anna" },
"payload": { "action": "send", "args": [] },
"created_at": "2026-11-17T11:42:05Z"
}
],
"has_more": false
}
Исходящие вебхуки
В кабинете, раздел «API», добавьте адрес своего сервера (только https) и выберите события. На каждое событие придёт POST с JSON:
{
"id": "evt_4kPq9ZxT2mLb7Hc1Wd5R",
"event": "widget.lead",
"created_at": 1763379725,
"data": { }
}
| Событие | Когда | data |
|---|---|---|
widget.action |
человек выполнил действие в виджете | widget, bot, message, action, args, user (id, first_name, last_name, username, language_code), result — ответ, который получил виджет |
widget.lead |
оставлена заявка | lead, widget, status, user, payload, created_at |
giveaway.finished |
розыгрыш проведён | widget, participants, winners — идентификаторы Telegram победителей |
message.failed |
Telegram отклонил отправку | message, widget, bot, chat_id, source, reason, telegram_error (code, description) |
ping |
кнопка «Проверить» в кабинете | endpoint |
Заголовки запроса: X-Widgram-Signature, X-Widgram-Event, X-Widgram-Delivery (номер доставки), X-Widgram-Attempt (номер попытки), User-Agent: Widgram-Webhooks/1.
Подпись
X-Widgram-Signature — HMAC-SHA256 тела запроса секретом точки (whsec_…), шестнадцатеричной строкой. Считайте подпись по «сырому» телу, до разбора JSON, и сравнивайте за постоянное время. Секрет показывается один раз при создании точки; его можно сменить.
# Ruby (Rack, Rails)
expected = OpenSSL::HMAC.hexdigest("SHA256", ENV.fetch("WIDGRAM_WEBHOOK_SECRET"), request.raw_post)
head :unauthorized unless Rack::Utils.secure_compare(expected, request.headers["X-Widgram-Signature"].to_s)
# Python (Flask)
import hashlib, hmac, os
expected = hmac.new(os.environ["WIDGRAM_WEBHOOK_SECRET"].encode(), request.get_data(), hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers.get("X-Widgram-Signature", "")):
abort(401)
// Node (Express): нужен сырой буфер тела — app.use(express.raw({ type: "application/json" }))
const crypto = require("node:crypto");
const expected = crypto.createHmac("sha256", process.env.WIDGRAM_WEBHOOK_SECRET).update(req.body).digest("hex");
const given = Buffer.from(req.get("X-Widgram-Signature") || "", "utf8");
if (given.length !== expected.length || !crypto.timingSafeEqual(given, Buffer.from(expected, "utf8"))) return res.sendStatus(401);
// PHP
$body = file_get_contents('php://input');
$expected = hash_hmac('sha256', $body, getenv('WIDGRAM_WEBHOOK_SECRET'));
if (!hash_equals($expected, $_SERVER['HTTP_X_WIDGRAM_SIGNATURE'] ?? '')) { http_response_code(401); exit; }
Доставка и повторы
- Успех — любой ответ
2xxза 10 секунд. Тело ответа не читается. Редиректы не выполняются. - При ошибке — повторы через 1 минуту, 5 минут, 30 минут, 2 часа, 6 часов и 15 часов: всего 7 попыток за сутки. Тело и подпись при повторе те же; одно событие различайте по
id. - После седьмой неудачи точка отключается, а владельцу аккаунта пишет бот. События, созданные за время отключения, не сохраняются. Включить точку снова можно в кабинете.
- Порядок событий не гарантируется. Одно событие может прийти дважды — обрабатывайте по
idидемпотентно. - Адрес должен быть публичным: запросы в частные и локальные сети не отправляются, проверка идёт после разрешения имени при каждой попытке.
- Журнал доставок с кодами ответов виден в кабинете и хранится 30 дней.
Примеры: отправить виджет
# Ruby
require "net/http"
require "json"
uri = URI("https://api.example.com/api/v1/widgets/w_8fK2mQ9xTa/send")
request = Net::HTTP::Post.new(uri, "Authorization" => "Bearer #{ENV.fetch('WIDGRAM_API_KEY')}",
"Content-Type" => "application/json", "Idempotency-Key" => "order-1042")
request.body = JSON.generate(chat_id: 111_111_111, chat_data: { s: 1 })
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
message_id = JSON.parse(response.body).fetch("id") if response.code == "201"
# Python
import os, requests
response = requests.post(
"https://api.example.com/api/v1/widgets/w_8fK2mQ9xTa/send",
headers={"Authorization": f"Bearer {os.environ['WIDGRAM_API_KEY']}", "Idempotency-Key": "order-1042"},
json={"chat_id": 111111111, "chat_data": {"s": 1}},
timeout=15,
)
response.raise_for_status()
message_id = response.json()["id"]
// Node 18+
const response = await fetch("https://api.example.com/api/v1/widgets/w_8fK2mQ9xTa/send", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.WIDGRAM_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": "order-1042",
},
body: JSON.stringify({ chat_id: 111111111, chat_data: { s: 1 } }),
});
if (!response.ok) throw new Error((await response.json()).error.code);
const { id: messageId } = await response.json();
// PHP
$ch = curl_init('https://api.example.com/api/v1/widgets/w_8fK2mQ9xTa/send');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('WIDGRAM_API_KEY'),
'Content-Type: application/json',
'Idempotency-Key: order-1042',
],
CURLOPT_POSTFIELDS => json_encode(['chat_id' => 111111111, 'chat_data' => ['s' => 1]]),
]);
$message = json_decode(curl_exec($ch), true);
$messageId = $message['id'] ?? null;
Рецепты
Статус заказа в магазине
- В кабинете создайте виджет из шаблона «Статус заказа», задайте шаги и опубликуйте.
- Когда заказ оформлен, отправьте виджет покупателю:
POST /widgets/:id/sendсchat_data: {"s": 1}иIdempotency-Key— номером заказа. Сохранитеidсообщения рядом с заказом. - При смене этапа вызовите
PATCH /messages/:id/state:{"chat_data": {"s": 3, "t": "Курьер выехал", "eta": 1763400000}}. Виджет у покупателя обновится сам, без нового сообщения.
Поля состояния шаблона: s — номер текущего шага с единицы, t — пояснение под ним, eta — ожидаемое время в секундах Unix.
Конструктор ботов с блоком «HTTP-запрос»
Подойдёт любой конструктор, который умеет отправлять HTTP-запрос с заголовками и телом JSON. Адрес — POST https://api.example.com/api/v1/widgets/<идентификатор виджета>/send, заголовки Authorization: Bearer <ключ> и Content-Type: application/json, тело {"chat_id": <переменная с идентификатором пользователя Telegram>}.
Отправка идёт от системного бота Widgram, поэтому человек должен сначала начать с ним чат — например, открыв ссылку виджета (link в карточке). Чтобы отправка шла от своего бота, подключите его в разделе «Боты» кабинета и выберите на странице «Поделиться» виджета — или передайте его идентификатор в поле bot_id.
Свой бот со своим сервером (режим send_only)
Вебхук бота остаётся у вас. Каждое обновление с ключом widget_query или shared_widget_query пересылайте в POST /bots/:id/updates и, если в ответе handled: true, больше ничего с ним не делайте. Отвечать на такой запрос сами не должны: Telegram ждёт ровно один ответ, и его отправляем мы.