Widgram public API
The API lets you send widgets and change their state from your CRM, store or bot, read statistics and leads, and receive events on your own server.
In the examples below https://api.example.com is the address of your installation (API_HOST) and wg_live_… is a key.
Basics
| Address | https://<API_HOST>/api/v1 |
| Key | the Authorization: Bearer wg_live_… header. Issued in the cabinet, the API section; shown once. Only its hash is stored |
| Format | requests and responses are UTF-8 JSON (Content-Type: application/json). The request body is an object of at most 256 KB |
| Identifiers | widget w_…, message m_…, bot b_… — the same ones the cabinet shows |
| Time | ISO 8601 in UTC (2026-11-17T12:00:00Z); statistics dates are YYYY-MM-DD, days are UTC days |
| Language of error texts | Accept-Language: ru or en, or ?locale=en |
| Limit | 60 requests per second per key, shared by all methods. Above it: 429 with Retry-After: 1 |
Errors
Every error has the same shape:
{ "error": { "code": "state_source", "message": "This state is built by the widget engine and cannot be changed from outside." } }
Rely on code and the response status; message is a text for a person and may change.
| Status | code |
When |
|---|---|---|
| 400 | invalid_json |
the body is not JSON |
| 400 | idempotency_key_invalid |
Idempotency-Key is empty, longer than 255 characters or has non-printable or non-ASCII characters |
| 401 | unauthorized |
the key is missing, wrong or revoked |
| 402 | mau_limit |
the plan's active users limit is exhausted |
| 403 | plan_required |
the method is not available on the account's plan |
| 403 | moderation_required, wallet_forbidden, bot_blocked |
the widget has not passed review; a wallet widget through the system bot; the user blocked the bot |
| 404 | not_found, bot_not_found |
no such object, or it belongs to another account |
| 409 | state_source |
the state is built by the widget engine and cannot be changed from outside |
| 409 | widget_inactive, widget_not_published, version_broken, message_unavailable, bot_inactive, bot_mode, bot_unauthorized, no_bot, update_in_progress, idempotency_in_progress |
the object is in a state where the action is impossible |
| 413 | payload_too_large |
the body is larger than 256 KB |
| 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 |
invalid request data |
| 429 | rate_limited, repeat, throttled, daily_limit |
too often; see Retry-After |
| 502 | telegram_unavailable |
Telegram did not answer; the request may be retried |
Idempotency
All mutating methods (POST, PATCH) accept the Idempotency-Key header: any string of up to 255 printable ASCII characters without spaces, for example an order number.
- The request runs once. A retry with the same key and the same body returns the stored response and the
Idempotent-Replayed: trueheader. - The same key with a different request gives
422 idempotency_key_reused. - While the first request is still running, a retry gets
409 idempotency_in_progress. - Only successful responses are remembered. After an error nothing has changed, so a request with the same key runs again.
- A response is kept for 24 hours. Keys of different accounts do not collide.
What is available on which plan
| Methods | From plan |
|---|---|
POST /compile |
any, a key is optional |
GET /widgets, GET /widgets/:id, POST /widgets/:id/send, PATCH /messages/:id/state, PATCH /widgets/:id/state |
Start |
GET /widgets/:id/stats, GET /leads, POST /bots/:id/updates, outgoing webhooks |
Pro |
Methods
POST /compile
Validate and compress widget HTML. Without a key: 10 requests per minute from one address; with a key the key's limit applies. The only method open to browser requests from other sites (CORS).
curl -X POST https://api.example.com/api/v1/compile \
-H "Content-Type: application/json" \
-d '{"html": "<h3>Hello</h3><button>Press</button>"}'
Response: html (the compressed code), size_raw, size_zlib, ok, issues[] (linter findings with level, code, line, message, fix_hint), manifest, limits. The code may also be sent as the request body with Content-Type: text/html.
GET /widgets
The account's widgets, newest first. Archived widgets are hidden unless you ask for status=archived.
Parameters: status (draft, active, paused, archived), limit (1–100, 50 by default), starting_after (the identifier of the last widget you received).
{
"data": [
{
"id": "w_8fK2mQ9xTa",
"name": "Order status",
"template": "status",
"status": "active",
"moderation_status": "approved",
"published": true,
"caption": "Your order",
"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
}
The state field says who writes the state: engine — the widget engine builds it (poll, quiz, wheel) and it cannot be changed from outside; raw — it is written through the API as is; null — the widget has no such state.
GET /widgets/:id
The card of one widget: the same object.
POST /widgets/:id/send
Send a published widget to a chat.
| Field | Type | |
|---|---|---|
chat_id |
number | required. In a private chat this is the Telegram user identifier |
bot_id |
string | a bot of the account (b_…). Without it: the widget's default bot, otherwise the system bot |
chat_data |
string, object or null |
the initial state of the message, up to 1024 bytes. An object is serialised to compact JSON. Only if the widget's state.chat_data is not engine |
caption |
string | a caption instead of the one in the widget settings, up to 1024 characters |
reply_markup |
object | the keyboard under the message in Bot API format |
disable_notification |
boolean | send silently |
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}}'
Response 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"
}
Keep the id: it is how the message state is changed later.
Special responses: 429 repeat — this widget has just been sent to this person, retry in 10 seconds; 429 throttled — the bot's queue is busy or Telegram asked to wait, the time is in Retry-After; 402 mau_limit — the plan limit is exhausted; 403 bot_blocked — the user never started a chat with the bot or has blocked it.
Through the system bot a widget is sent only after review (moderation_status: approved) and only to people who started a chat with the bot themselves — that is how Telegram works.
PATCH /messages/:id/state
Change the chat_data of a sent message, for example the order stage. :id is the identifier from the send response.
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": "The courier is on the way", "eta": 1763400000}}'
chat_data is a string, an object or null (clear). Response 200: the message object with the new chat_data and pending: true. The write is accepted at once and a background process carries it to Telegram, usually within seconds. Several writes in a row are merged: Telegram receives the last one.
409 state_source — the state of this message is built by the widget engine. 409 message_unavailable — the message was not sent, was deleted, or the bot is blocked.
PATCH /widgets/:id/state
Change the shared state of a widget — what all its recipients see.
Option 1: the whole public_data, for widgets with state.public_data: "raw":
{ "public_data": { "price": 990, "left": 3 } }
Option 2: individual fields that the template declares editable (currently the end date of the countdown and the giveaway):
{ "fields": { "end": 1767225600 } }
The request must contain exactly one of the two keys. Response 200: { "id": "w_…", "revision": 7, "public_data": "…" } — the revision number and the text the widgets will receive. 409 state_source — the engine builds this state, or the field is not editable.
POST /bots/:id/updates
For a bot in send_only mode, when the bot's webhook stays with your server. To make widget buttons work in such a bot, forward its updates to us: the request body is the Telegram update as is.
{ "handled": true, "outcome": "processed" }
handled |
outcome |
Meaning |
|---|---|---|
true |
processed |
it is a query of our widget; we answered it ourselves |
true |
duplicate |
we have already processed this update |
false |
foreign |
not ours — handle it yourself |
Ours are only widget_query and shared_widget_query for widgets that we sent. You may forward every update or only these two kinds. 409 bot_mode — the bot is connected in another mode and we receive its updates ourselves.
A bot is connected in the dashboard, under Bots, in the Send only mode; its identifier (b_…) is shown on the bot's page.
GET /widgets/:id/stats
Widget statistics by day. Parameters from and to (YYYY-MM-DD); the last 30 days by default, at most 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": "Coffee", "value": 130 }, { "label": "Tea", "value": 80 } ]
}
unique_users in totals is the sum over days, not the number of distinct people in the period. distribution exists for the poll and the rating, and is null for the rest. Views are only counted for widgets with queries allowed.
GET /leads
Leads, newest first. Parameters: widget (w_…), status (new, in_progress, done, spam), limit (1–100), starting_after (the id of the last lead you received).
{
"data": [
{
"id": 381,
"widget": "w_Qm3xL8rT2a",
"status": "new",
"user": { "id": 111111111, "first_name": "Anna", "username": "anna" },
"payload": { "action": "send", "args": [] },
"created_at": "2026-11-17T11:42:05Z"
}
],
"has_more": false
}
Outgoing webhooks
In the cabinet, the API section, add the address of your server (https only) and choose the events. Each event arrives as a POST with JSON:
{
"id": "evt_4kPq9ZxT2mLb7Hc1Wd5R",
"event": "widget.lead",
"created_at": 1763379725,
"data": { }
}
| Event | When | data |
|---|---|---|
widget.action |
a person performed an action in a widget | widget, bot, message, action, args, user (id, first_name, last_name, username, language_code), result — the answer the widget received |
widget.lead |
a lead was left | lead, widget, status, user, payload, created_at |
giveaway.finished |
a giveaway was drawn | widget, participants, winners — Telegram identifiers of the winners |
message.failed |
Telegram rejected a send | message, widget, bot, chat_id, source, reason, telegram_error (code, description) |
ping |
the Test button in the cabinet | endpoint |
Request headers: X-Widgram-Signature, X-Widgram-Event, X-Widgram-Delivery (delivery number), X-Widgram-Attempt (attempt number), User-Agent: Widgram-Webhooks/1.
Signature
X-Widgram-Signature is the HMAC-SHA256 of the request body with the endpoint secret (whsec_…), as a hex string. Compute it over the raw body, before parsing JSON, and compare in constant time. The secret is shown once when the endpoint is created; it can be changed.
# 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): the raw body buffer is required — 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; }
Delivery and retries
- Success is any
2xxresponse within 10 seconds. The response body is not read. Redirects are not followed. - On an error we retry after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 15 hours: 7 attempts within a day. The body and the signature of a retry are the same; tell events apart by
id. - After the seventh failure the endpoint is disabled and the bot writes to the account owner. Events created while it is disabled are not kept. The endpoint can be enabled again in the cabinet.
- The order of events is not guaranteed. One event may arrive twice — handle it idempotently by
id. - The address must be public: requests to private and local networks are not sent, and the check runs after name resolution on every attempt.
- The delivery log with response codes is visible in the cabinet and kept for 30 days.
Examples: send a widget
# 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;
Recipes
Order status in a store
- In the cabinet create a widget from the Order status template, set the steps and publish it.
- When an order is placed, send the widget to the buyer:
POST /widgets/:id/sendwithchat_data: {"s": 1}and the order number asIdempotency-Key. Store the messageidnext to the order. - When the stage changes, call
PATCH /messages/:id/state:{"chat_data": {"s": 3, "t": "The courier is on the way", "eta": 1763400000}}. The buyer's widget updates by itself, without a new message.
The template's state fields: s — the number of the current step starting from one, t — a note under it, eta — the expected time in Unix seconds.
A bot builder with an HTTP request block
Any builder that can send an HTTP request with headers and a JSON body will do. The address is POST https://api.example.com/api/v1/widgets/<widget identifier>/send, the headers are Authorization: Bearer <key> and Content-Type: application/json, the body is {"chat_id": <the variable with the Telegram user identifier>}.
The widget is sent by the Widgram system bot, so the person has to start a chat with it first — for example by opening the widget link (link in the card). To send from your own bot, connect it under Bots in the dashboard and choose it on the Share page of the widget — or pass its identifier in the bot_id field.
Your own bot with your own server (send_only mode)
The bot's webhook stays with you. Forward every update with the widget_query or shared_widget_query key to POST /bots/:id/updates, and if the response says handled: true, do nothing else with it. You must not answer such a query yourself: Telegram expects exactly one answer, and we send it.