Перейти к содержимому
Widgram

Публичный 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;

Рецепты

Статус заказа в магазине

  1. В кабинете создайте виджет из шаблона «Статус заказа», задайте шаги и опубликуйте.
  2. Когда заказ оформлен, отправьте виджет покупателю: POST /widgets/:id/send с chat_data: {"s": 1} и Idempotency-Key — номером заказа. Сохраните id сообщения рядом с заказом.
  3. При смене этапа вызовите 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 ждёт ровно один ответ, и его отправляем мы.