Telegram Bot API

مثال ویجت تلگرام: کد کامل HTML و ربات پایتون

· 12 دقیقه مطالعه

این مثال‌های ویجت تلگرام کامل و آماده اجرا هستند: هر کدام HTML ویجت (خیلی کمتر از سقف 4 کیلوبایت فشرده)، کد ربات پایتون با requests و long polling و توضیح چیزی که کاربر می‌بیند را دارد. با یک کارت سفارش ثابت شروع می‌کنیم، با شمارنده درخواست اضافه می‌کنیم و در آخر نظرسنجی زنده را به صورت ویجت اشتراکی می‌سازیم. اگر با ویجت‌ها آشنا نیستید، اول ویجت تلگرام چیست را بخوانید.

قبل از شروع: در محیط production ویجت‌ها فعلاً فقط در چت خصوصی با ربات کار می‌کنند و با محتوای محافظت‌شده ارسال می‌شوند، پس قابل فوروارد نیستند. گروه‌ها، حالت inline و فوروارد فقط روی سرور تست کار می‌کنند. همه مثال‌های زیر در چت خصوصی اجرا می‌شوند.

پیش‌نیازها: پایتون 3 با requests (pip install requests)، توکن ربات (گرفتن توکن ربات تلگرام) و چت آیدی خودتان. هر ویجت را کنار اسکریپت ربات به صورت فایل ذخیره کنید. قبل از نوشتن کد هم می‌توانید هر ویجت را در فرم sendWidget در Bot API Tester بچسبانید و نتیجه را در چت ببینید.

مثال 1: کارت سفارش ثابت (بدون درخواست)

خلاصه سفارشی که ربات خط وضعیتش را با پیشرفت سفارش به‌روز می‌کند. ویجت هیچ درخواستی به ربات نمی‌فرستد، پس بدون allow_queries ارسال می‌شود. وضعیت در chat_data است و ویجت آن را در شروع و با هر رویداد chatDataChanged رسم می‌کند. پیام کپشن و یک کیبورد inline هم زیر ویجت دارد.

order.html (966 بایت، 583 بایت فشرده):

<style>
h3{margin:0 0 6px}
.row{display:flex;justify-content:space-between;gap:12px}
.st{margin-top:10px;padding:6px 10px;border-radius:8px;background:var(--tg-theme-secondary-bg-color)}
.hint{color:var(--tg-theme-hint-color);font-size:.87em}
</style>
<h3>سفارش #1042</h3>
<div class="row"><span>2 × پیتزا مارگاریتا</span><span>$19.00</span></div>
<div class="row"><span>1 × لیموناد</span><span>$4.50</span></div>
<div class="row"><strong>جمع کل</strong><strong>$23.50</strong></div>
<div class="st"><span id="st">سفارش ثبت شد</span> <span class="hint" id="at"></span></div>
<script>
const W = window.TelegramWidget;
function render() {
  let s = null;
  try { s = JSON.parse(W.chatData); } catch (e) {}
  if (!s) return;
  document.getElementById('st').textContent = s.status;
  document.getElementById('at').textContent = s.at ? 'ساعت ' + s.at : '';
}
if (W) W.onEvent('chatDataChanged', render);
render();
</script>

bot_order.py: کارت را می‌فرستد و بعد سه بار وضعیتش را عوض می‌کند:

import json
import time
import requests

TOKEN = "123456789:AAEexampleTokenReplaceWithYours"
API = f"https://api.telegram.org/bot{TOKEN}"
CHAT_ID = 123456789  # چت خصوصی شما با ربات
HTML = open("order.html", encoding="utf-8").read()


def call(method, **params):
    r = requests.post(f"{API}/{method}", json=params, timeout=40).json()
    if not r["ok"]:
        if "message is not modified" in r.get("description", ""):
            return True  # ویجت همین وضعیت را نشان می‌دهد
        raise RuntimeError(f"{method}: {r['description']}")
    return r["result"]


msg = call(
    "sendWidget",
    chat_id=CHAT_ID,
    html=HTML,
    chat_data=json.dumps({"status": "سفارش ثبت شد"}),
    caption="سفارش #1042: $23.50",
    reply_markup={"inline_keyboard": [[
        {"text": "پیگیری سفارش", "url": "https://example.com/orders/1042"},
    ]]},
)

for status in ["در حال آماده‌سازی", "در راه", "تحویل شد"]:
    time.sleep(60)  # در ربات واقعی: وقتی سیستم سفارش تغییری گزارش می‌دهد
    call(
        "editMessageWidgetData",
        chat_id=CHAT_ID,
        message_id=msg["message_id"],
        chat_data=json.dumps({"status": status, "at": time.strftime("%H:%M")}),
    )
// bot_order.mjs
import { readFile } from "node:fs/promises";
import { setTimeout as sleep } from "node:timers/promises";

const TOKEN = "123456789:AAEexampleTokenReplaceWithYours";
const API = `https://api.telegram.org/bot${TOKEN}`;
const CHAT_ID = 123456789; // چت خصوصی شما با ربات
const HTML = await readFile("order.html", "utf-8");

async function call(method, params = {}) {
  const res = await fetch(`${API}/${method}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(params),
    signal: AbortSignal.timeout(40_000),
  });
  const r = await res.json();
  if (!r.ok) {
    if ((r.description ?? "").includes("message is not modified")) {
      return true; // ویجت همین وضعیت را نشان می‌دهد
    }
    throw new Error(`${method}: ${r.description}`);
  }
  return r.result;
}

function hhmm() {
  return new Date().toTimeString().slice(0, 5); // مثل time.strftime("%H:%M")
}

const msg = await call("sendWidget", {
  chat_id: CHAT_ID,
  html: HTML,
  chat_data: JSON.stringify({ status: "سفارش ثبت شد" }),
  caption: "سفارش #1042: $23.50",
  reply_markup: { inline_keyboard: [[
    { text: "پیگیری سفارش", url: "https://example.com/orders/1042" },
  ]] },
});

for (const status of ["در حال آماده‌سازی", "در راه", "تحویل شد"]) {
  await sleep(60_000); // در ربات واقعی: وقتی سیستم سفارش تغییری گزارش می‌دهد
  await call("editMessageWidgetData", {
    chat_id: CHAT_ID,
    message_id: msg.message_id,
    chat_data: JSON.stringify({ status, at: hhmm() }),
  });
}

کاربر چه می‌بیند: کارتی با رنگ‌های چت، اقلام سفارش، جمع کل و «سفارش ثبت شد»، کپشن «سفارش #1042: $23.50» و دکمه «پیگیری سفارش» زیر آن. هر دقیقه خط وضعیت بی‌صدا عوض می‌شود، مثلاً «در حال آماده‌سازی» با «ساعت 19:40» خاکستری؛ ویرایش ویجت نه برچسب «ویرایش‌شده» دارد نه اعلان. زمان کنار وضعیت باعث می‌شود وضعیت مثل یک عکس لحظه‌ای خوانده شود، نه نوار پیشرفتی که باید منتظرش ماند.

مثال 2: شمارنده با درخواست‌های widget_query

شمارنده‌ای با دکمه‌های +1 و صفر کن. هر لمس TelegramWidget.request() را صدا می‌زند؛ ربات عدد را به‌روز می‌کند، آن را با editMessageWidgetData در chat_data می‌نویسد و همان مقدار را با answerWidgetQuery برمی‌گرداند تا ویجت فوراً نشانش دهد. شماره نسخه r باعث می‌شود ویجت وضعیت قدیمی‌تری را که بعد از وضعیت جدیدتر می‌رسد نادیده بگیرد.

counter.html (1271 بایت، 736 بایت فشرده):

<style>
.n{font-size:2.4em;font-weight:600;text-align:center;font-variant-numeric:tabular-nums}
.row{display:flex;gap:8px}
.row button{flex:1}
#m{min-height:1.35em;margin-top:6px;text-align:center;color:var(--tg-theme-hint-color);font-size:.87em}
</style>
<div class="n" id="n">0</div>
<div class="row"><button id="like">+1</button><button id="reset">صفر کن</button></div>
<div id="m"></div>
<script>
const W = window.TelegramWidget, $ = (id) => document.getElementById(id);
let rev = -1;
function show(text) {
  let s = null;
  try { s = JSON.parse(text); } catch (e) {}
  if (!s || typeof s.n !== 'number' || s.r < rev) return false;
  rev = s.r;
  $('n').textContent = s.n;
  return true;
}
function ask(data) {
  if (!W) return;
  $('m').textContent = 'در حال ارسال…';
  W.request(data).then((a) => {
    $('m').textContent = show(a.result) ? '' : 'برای شمارنده جدید /start بفرستید';
  }, (e) => {
    $('m').textContent = e.code === 'TIMEOUT' ? 'ربات پاسخ نداد' : 'ارسال نشد: ' + e.code;
  });
}
$('like').addEventListener('click', () => ask('like'));
$('reset').addEventListener('click', () => ask('reset'));
if (W) {
  W.onEvent('chatDataChanged', () => show(W.chatData));
  show(W.chatData);
}
</script>

نکات کلیدی کد ویجت:

bot_counter.py: long polling با allowed_updates که widget_query را شامل می‌شود:

import json
import time
import requests

TOKEN = "123456789:AAEexampleTokenReplaceWithYours"
API = f"https://api.telegram.org/bot{TOKEN}"
HTML = open("counter.html", encoding="utf-8").read()
counters = {}  # (chat_id, message_id) -> {"n": count, "r": revision}


def call(method, **params):
    r = requests.post(f"{API}/{method}", json=params, timeout=40).json()
    if r["ok"]:
        return r["result"]
    if "message is not modified" in r.get("description", ""):
        return True  # چیزی برای تغییر نیست: موفق حساب کن
    print(f"{method} failed: {r.get('description')}")
    return None


def dump(state):
    return json.dumps(state, separators=(",", ":"))


def send_counter(chat_id):
    state = {"n": 0, "r": 0}
    msg = call("sendWidget", chat_id=chat_id, html=HTML, chat_data=dump(state),
               caption="برای شمردن +1 را لمس کنید", allow_queries=True)
    if msg:
        counters[(chat_id, msg["message_id"])] = state


def on_widget_query(q):
    key = (q["chat"]["id"], q["message_id"])
    state = counters.get(key)
    if state is None or q["data"] not in ("like", "reset"):
        # پیام ناشناخته (مثلاً ربات ری‌استارت شده) یا داده ناشناخته: باز هم جواب بده
        call("answerWidgetQuery", widget_query_id=q["id"])
        return
    new = {"n": state["n"] + 1 if q["data"] == "like" else 0, "r": state["r"] + 1}
    if call("editMessageWidgetData", chat_id=key[0], message_id=key[1],
            chat_data=dump(new)):
        counters[key] = new  # فقط بعد از موفقیت ویرایش ثبت کن
    call("answerWidgetQuery", widget_query_id=q["id"], data=dump(counters[key]))


def main():
    offset = 0
    while True:
        updates = call("getUpdates", offset=offset, timeout=30,
                       allowed_updates=["message", "widget_query"])
        if updates is None:
            time.sleep(3)
            continue
        for u in updates:
            offset = u["update_id"] + 1
            if "widget_query" in u:
                on_widget_query(u["widget_query"])
            elif u.get("message", {}).get("text") == "/start":
                send_counter(u["message"]["chat"]["id"])


main()
// bot_counter.mjs
import { readFile } from "node:fs/promises";
import { setTimeout as sleep } from "node:timers/promises";

const TOKEN = "123456789:AAEexampleTokenReplaceWithYours";
const API = `https://api.telegram.org/bot${TOKEN}`;
const HTML = await readFile("counter.html", "utf-8");
const counters = new Map(); // "chat_id:message_id" -> {n: count, r: revision}

async function call(method, params = {}) {
  const res = await fetch(`${API}/${method}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(params),
    signal: AbortSignal.timeout(40_000),
  });
  const r = await res.json();
  if (r.ok) return r.result;
  if ((r.description ?? "").includes("message is not modified")) {
    return true; // چیزی برای تغییر نیست: موفق حساب کن
  }
  console.log(`${method} failed: ${r.description}`);
  return null;
}

function dump(state) {
  return JSON.stringify(state); // از قبل فشرده است، مثل separators=(",", ":")
}

async function sendCounter(chatId) {
  const state = { n: 0, r: 0 };
  const msg = await call("sendWidget", {
    chat_id: chatId, html: HTML, chat_data: dump(state),
    caption: "برای شمردن +1 را لمس کنید", allow_queries: true,
  });
  if (msg) counters.set(`${chatId}:${msg.message_id}`, state);
}

async function onWidgetQuery(q) {
  const chatId = q.chat.id, messageId = q.message_id;
  const key = `${chatId}:${messageId}`;
  const state = counters.get(key);
  if (state === undefined || !["like", "reset"].includes(q.data)) {
    // پیام ناشناخته (مثلاً ربات ری‌استارت شده) یا داده ناشناخته: باز هم جواب بده
    await call("answerWidgetQuery", { widget_query_id: q.id });
    return;
  }
  const next = { n: q.data === "like" ? state.n + 1 : 0, r: state.r + 1 };
  if (await call("editMessageWidgetData", {
    chat_id: chatId, message_id: messageId, chat_data: dump(next),
  })) {
    counters.set(key, next); // فقط بعد از موفقیت ویرایش ثبت کن
  }
  await call("answerWidgetQuery", { widget_query_id: q.id, data: dump(counters.get(key)) });
}

async function main() {
  let offset = 0;
  while (true) {
    const updates = await call("getUpdates", {
      offset, timeout: 30, allowed_updates: ["message", "widget_query"],
    });
    if (updates === null) {
      await sleep(3000);
      continue;
    }
    for (const u of updates) {
      offset = u.update_id + 1;
      if (u.widget_query) {
        await onWidgetQuery(u.widget_query);
      } else if (u.message?.text === "/start") {
        await sendCounter(u.message.chat.id);
      }
    }
  }
}

main();

کاربر چه می‌بیند: بعد از /start یک «0» بزرگ با دو دکمه بومی. با لمس +1 ابتدا «در حال ارسال…» و بعد عدد جدید نمایش داده می‌شود. اگر ربات خاموش باشد، بعد از 15 ثانیه پیام «ربات پاسخ نداد» (TIMEOUT) می‌آید. بعد از ری‌استارت ربات، دیکشنری حافظه خالی است، پس ربات بدون داده جواب می‌دهد و ویجت از کاربر می‌خواهد /start بفرستد؛ ربات واقعی وضعیت را در دیتابیس و بر اساس چت و پیام نگه می‌دارد.

مثال 3: نظرسنجی زنده با ویجت اشتراکی تلگرام

یک نظرسنجی که در چت‌های خصوصی زیادی با یک مجموعه نتیجه نمایش داده می‌شود. اولین sendWidget با is_shared و allow_queries ویجت اشتراکی را می‌سازد؛ ربات widget.id را از پیام برگشتی ذخیره می‌کند و بعداً همان نظرسنجی را با sendSharedWidget به هر کاربری که /start بفرستد نشان می‌دهد. رأی‌ها با editSharedWidgetData در public_data نوشته می‌شوند و همه پیام‌ها جمع جدید را می‌گیرند.

poll.html (1877 بایت، 1053 بایت فشرده):

<style>
.o{display:block;width:100%;margin:6px 0;text-align:left}
.me{outline:2px solid var(--tg-theme-button-color)}
.bar{height:4px;margin-top:4px;border-radius:2px;background:var(--tg-theme-button-color)}
.h{color:var(--tg-theme-hint-color);font-size:.87em}
</style>
<strong>آموزش بعدی با کدام زبان باشد؟</strong>
<div id="list"></div>
<div class="h" id="msg"></div>
<script>
const W = window.TelegramWidget, $ = (id) => document.getElementById(id);
const OPTS = ['Python', 'JavaScript', 'Go'];
let st = { v: [0, 0, 0], r: -1 }, mine = null;
try { mine = JSON.parse(localStorage.getItem('vote')); } catch (e) {}
function take(text) {
  let s = null;
  try { s = JSON.parse(text); } catch (e) {}
  if (s && Array.isArray(s.v) && s.r >= st.r) { st = s; draw(); }
}
function draw() {
  const total = st.v.reduce((a, b) => a + b, 0);
  $('list').replaceChildren(...OPTS.map((name, i) => {
    const b = document.createElement('button');
    const pct = total ? Math.round(st.v[i] / total * 100) : 0;
    b.className = 'o' + (mine === i ? ' me' : '');
    b.innerHTML = name + ' <span class="h">' + pct + '% (' + st.v[i] + ')</span><div class="bar" style="width:' + pct + '%"></div>';
    b.addEventListener('click', () => vote(i));
    return b;
  }));
}
function vote(i) {
  if (!W) return;
  $('msg').textContent = 'در حال ارسال…';
  W.request('vote:' + i).then((a) => {
    mine = i;
    try { localStorage.setItem('vote', String(i)); } catch (e) {}
    $('msg').textContent = 'رأی شما ثبت شد';
    take(a.result);
    draw();
  }, (e) => {
    $('msg').textContent = e.code === 'NOT_ALLOWED' ? 'برای رأی دادن ربات را باز کنید' : 'ارسال نشد: ' + e.code;
  });
}
if (W) {
  W.onEvent('publicDataChanged', () => take(W.publicData));
  W.watchPublicData();
  take(W.publicData);
}
draw();
</script>

ویجت watchPublicData() را صدا می‌زند؛ بدون آن، ویجت اشتراکی‌ای که روی صفحه است وضعیت مشترک جدید را فقط هنگام بارگذاری دوباره پیام می‌گیرد. تا وقتی نظرسنجی دیده می‌شود، اپ وضعیت مشترک را با دوره به‌روزرسانی ویجت می‌پرسد که ربات آن را با cache_time روی 10 ثانیه گذاشته است. انتخاب خود کاربر در localStorage می‌ماند که متعلق به همین پیام روی همین دستگاه است.

bot_poll.py: رأی‌ها بر اساس کاربر، ویرایش‌ها حداکثر یکی در ثانیه:

import json
import time
import requests

TOKEN = "123456789:AAEexampleTokenReplaceWithYours"
API = f"https://api.telegram.org/bot{TOKEN}"
ADMIN_CHAT_ID = 123456789  # چت خصوصی خودتان با ربات
HTML = open("poll.html", encoding="utf-8").read()
OPTIONS = 3
DB_FILE = "poll.json"

try:
    with open(DB_FILE) as f:
        db = json.load(f)
except FileNotFoundError:
    db = {"widget_id": None, "votes": {}, "r": 0}  # votes: user id -> option
dirty, last_edit = False, 0.0


def save():
    with open(DB_FILE, "w") as f:
        json.dump(db, f)


def call(method, **params):
    r = requests.post(f"{API}/{method}", json=params, timeout=40).json()
    if r["ok"]:
        return r["result"]
    if "message is not modified" in r.get("description", ""):
        return True
    print(f"{method} failed: {r.get('description')}")
    return None


def public_state():
    v = [0] * OPTIONS
    for option in db["votes"].values():
        v[option] += 1
    return json.dumps({"v": v, "r": db["r"]}, separators=(",", ":"))


def flush():
    """وضعیت مشترک را حداکثر یک بار در ثانیه بنویس (محدودیت ویجت اشتراکی)."""
    global dirty, last_edit
    if dirty and time.monotonic() - last_edit >= 1:
        last_edit = time.monotonic()
        if call("editSharedWidgetData", widget_id=db["widget_id"],
                public_data=public_state(), cache_time=10):
            dirty = False


def on_query(q):
    global dirty
    data = q["data"]
    if q.get("widget_id") == db["widget_id"] and data.startswith("vote:") \
            and data[5:].isdigit() and int(data[5:]) < OPTIONS:
        db["votes"][str(q["from"]["id"])] = int(data[5:])  # هر کاربر یک رأی
        db["r"] += 1
        save()
        dirty = True
    # رأی‌دهنده نتیجه را فوراً می‌بیند؛ بقیه از طریق ویرایش
    call("answerWidgetQuery", widget_query_id=q["id"], data=public_state())


def main():
    if not db["widget_id"]:
        # اولین ارسال با is_shared ویجت اشتراکی را می‌سازد
        msg = call("sendWidget", chat_id=ADMIN_CHAT_ID, html=HTML,
                   public_data=public_state(), is_shared=True, allow_queries=True,
                   caption="نظرسنجی: آموزش بعدی با کدام زبان باشد؟")
        db["widget_id"] = msg["widget"]["id"]
        save()
    offset = 0
    while True:
        updates = call("getUpdates", offset=offset, timeout=1 if dirty else 25,
                       allowed_updates=["message", "widget_query", "shared_widget_query"])
        if updates is None:
            time.sleep(3)
            continue
        for u in updates:
            offset = u["update_id"] + 1
            q = u.get("widget_query") or u.get("shared_widget_query")
            if q:
                on_query(q)
            elif u.get("message", {}).get("text") == "/start":
                call("sendSharedWidget", chat_id=u["message"]["chat"]["id"],
                     widget_id=db["widget_id"],
                     caption="نظرسنجی: آموزش بعدی با کدام زبان باشد؟")
        flush()


main()
// bot_poll.mjs
import { readFile, writeFile } from "node:fs/promises";
import { setTimeout as sleep } from "node:timers/promises";

const TOKEN = "123456789:AAEexampleTokenReplaceWithYours";
const API = `https://api.telegram.org/bot${TOKEN}`;
const ADMIN_CHAT_ID = 123456789; // چت خصوصی خودتان با ربات
const HTML = await readFile("poll.html", "utf-8");
const OPTIONS = 3;
const DB_FILE = "poll.json";

let db;
try {
  db = JSON.parse(await readFile(DB_FILE, "utf-8"));
} catch (e) {
  if (e.code !== "ENOENT") throw e;
  db = { widget_id: null, votes: {}, r: 0 }; // votes: user id -> option
}
let dirty = false, lastEdit = -Infinity;

async function save() {
  await writeFile(DB_FILE, JSON.stringify(db));
}

async function call(method, params = {}) {
  const res = await fetch(`${API}/${method}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(params),
    signal: AbortSignal.timeout(40_000),
  });
  const r = await res.json();
  if (r.ok) return r.result;
  if ((r.description ?? "").includes("message is not modified")) return true;
  console.log(`${method} failed: ${r.description}`);
  return null;
}

function publicState() {
  const v = new Array(OPTIONS).fill(0);
  for (const option of Object.values(db.votes)) v[option] += 1;
  return JSON.stringify({ v, r: db.r });
}

// وضعیت مشترک را حداکثر یک بار در ثانیه بنویس (محدودیت ویجت اشتراکی).
async function flush() {
  const now = performance.now() / 1000; // ثانیه‌های monotonic
  if (dirty && now - lastEdit >= 1) {
    lastEdit = now;
    if (await call("editSharedWidgetData", {
      widget_id: db.widget_id, public_data: publicState(), cache_time: 10,
    })) {
      dirty = false;
    }
  }
}

async function onQuery(q) {
  const data = q.data;
  const digits = data.slice(5);
  if (q.widget_id === db.widget_id && data.startsWith("vote:")
      && /^\d+$/.test(digits) && Number(digits) < OPTIONS) {
    db.votes[String(q.from.id)] = Number(digits); // هر کاربر یک رأی
    db.r += 1;
    await save();
    dirty = true;
  }
  // رأی‌دهنده نتیجه را فوراً می‌بیند؛ بقیه از طریق ویرایش
  await call("answerWidgetQuery", { widget_query_id: q.id, data: publicState() });
}

async function main() {
  if (!db.widget_id) {
    // اولین ارسال با is_shared ویجت اشتراکی را می‌سازد
    const msg = await call("sendWidget", {
      chat_id: ADMIN_CHAT_ID, html: HTML,
      public_data: publicState(), is_shared: true, allow_queries: true,
      caption: "نظرسنجی: آموزش بعدی با کدام زبان باشد؟",
    });
    db.widget_id = msg.widget.id;
    await save();
  }
  let offset = 0;
  while (true) {
    const updates = await call("getUpdates", {
      offset, timeout: dirty ? 1 : 25,
      allowed_updates: ["message", "widget_query", "shared_widget_query"],
    });
    if (updates === null) {
      await sleep(3000);
      continue;
    }
    for (const u of updates) {
      offset = u.update_id + 1;
      const q = u.widget_query || u.shared_widget_query;
      if (q) {
        await onQuery(q);
      } else if (u.message?.text === "/start") {
        await call("sendSharedWidget", {
          chat_id: u.message.chat.id,
          widget_id: db.widget_id,
          caption: "نظرسنجی: آموزش بعدی با کدام زبان باشد؟",
        });
      }
    }
    await flush();
  }
}

main();

کاربر چه می‌بیند: سه دکمه بومی با درصد و نوار. بعد از لمس، «رأی شما ثبت شد» می‌آید، گزینه کاربر قاب می‌گیرد و شمارش‌ها رأی او را فوراً (از پاسخ ربات) شامل می‌شوند. رأی دیگران حدوداً ظرف 10 ثانیه و بدون باز کردن دوباره چت ظاهر می‌شود.

مثال 4: پیش‌نمایش در مرورگر، بررسی حجم و خطاها

ویجت HTML است، پس پنجره مرورگر دسکتاپ با عرض 320 تا 430 پیکسل نگاه اول سریعی می‌دهد. بیرون از تلگرام TelegramWidget وجود ندارد، پس یک جایگزین بالای کد ویجت بگذارید. آن را در فایل جدای stub.html نگه دارید تا هرگز همراه ویجت ارسال نشود. این نسخه کوتاه‌شده جایگزین مستندات رسمی است که برای شمارنده تنظیم شده:

<style>:root{--tg-theme-bg-color:#fff;--tg-theme-text-color:#000;--tg-theme-hint-color:#707579;
--tg-theme-link-color:#3390ec;--tg-theme-button-color:#3390ec;--tg-theme-button-text-color:#fff;
--tg-theme-secondary-bg-color:#f1f1f4}body{max-width:360px}</style>
<script>
window.TelegramWidget = window.TelegramWidget || {
  profile: 1, colorScheme: 'light', themeParams: {}, isActive: true, isPreview: false,
  isForward: false, chatType: 'private', viewer: { id: 1, first_name: 'Test' },
  chatData: '{"n":4,"r":1}', publicData: null, wallet: null,
  HapticFeedback: { impactOccurred() { return this; }, notificationOccurred() { return this; }, selectionChanged() { return this; } },
  onEvent() {}, offEvent() {}, ready() {}, watchPublicData() {}, unwatchPublicData() {},
  openLink: (url) => console.log('openLink', url), openTelegramLink: (url) => console.log('openTelegramLink', url),
  copyText: (text) => console.log('copyText', text),
  request: (data) => { console.log('request', data); return Promise.resolve({ result: '{"n":5,"r":2}' }); },
};
</script>

preview.py فایل stub و ویجت را در preview.html به هم می‌چسباند:

import sys

stub = open("stub.html", encoding="utf-8").read()
widget = open(sys.argv[1], encoding="utf-8").read()
with open("preview.html", "w", encoding="utf-8") as f:
    f.write(stub + widget)
print("Open preview.html in a browser window 320-430 px wide")
// preview.mjs
import { readFile, writeFile } from "node:fs/promises";

const stub = await readFile("stub.html", "utf-8");
const widget = await readFile(process.argv[2], "utf-8");
await writeFile("preview.html", stub + widget, "utf-8");
console.log("Open preview.html in a browser window 320-430 px wide");

python3 preview.py counter.html را اجرا کنید، preview.html را باز کنید و در کنسول دنبال request like بگردید. chatData، publicData، viewer و isForward را برای حالت‌هایی که می‌خواهید ببینید تغییر دهید. یادتان باشد مرورگر چیزهایی را رسم می‌کند که تلگرام حذف می‌کند (input، vh، اسکرول) و هیچ محدودیتی را اعمال نمی‌کند.

check_widget.py حجم را دقیقاً مثل سرور (zlib پایتون در سطح 9) قبل از ارسال حساب می‌کند. نسخه Node.js در پروژه‌های JavaScript به کار می‌آید، اما zlib در Node ممکن است چند بایت اختلاف داشته باشد؛ پس نزدیک 4096 به عدد پایتون اعتماد کنید:

import sys
import zlib

raw = open(sys.argv[1], "rb").read()
raw.decode("utf-8")  # برای UTF-8 نامعتبر UnicodeDecodeError می‌دهد
packed = len(zlib.compress(raw, 9))
print(f"{len(raw)} bytes, {packed} bytes after zlib level 9")
if b"\x00" in raw:
    sys.exit("NUL character: the server answers INPUT_MEDIA_WIDGET_HTML_INVALID")
if len(raw) > 32768 or packed > 4096:
    sys.exit("too large: the server answers INPUT_MEDIA_WIDGET_TOO_LARGE")
print("OK")
// check_widget.mjs
import { readFile } from "node:fs/promises";
import { deflateSync } from "node:zlib";

function fail(message) {
  console.error(message);
  process.exit(1);
}

const raw = await readFile(process.argv[2]);
new TextDecoder("utf-8", { fatal: true }).decode(raw); // برای UTF-8 نامعتبر TypeError می‌دهد
// zlib همراه Node ممکن است چند بایت با zlib سرور (پایتون) فرق داشته باشد:
// کمی پایین‌تر از 4096 حاشیه بگذارید
const packed = deflateSync(raw, { level: 9 }).length;
console.log(`${raw.length} bytes, ${packed} bytes after zlib level 9`);
if (raw.includes(0)) {
  fail("NUL character: the server answers INPUT_MEDIA_WIDGET_HTML_INVALID");
}
if (raw.length > 32768 || packed > 4096) {
  fail("too large: the server answers INPUT_MEDIA_WIDGET_TOO_LARGE");
}
console.log("OK");
$ python3 check_widget.py counter.html
1271 bytes, 736 bytes after zlib level 9
OK

خطاهایی که ممکن است هنگام کار با این مثال‌ها از Bot API بگیرید:

خطاعلتراه‌حل
INPUT_MEDIA_WIDGET_TOO_LARGEHTML بیش از 32768 بایت یا بیش از 4096 بایت فشردهکامنت‌ها و کد بی‌استفاده را حذف کنید، SVG و CSS را به تصاویر data: ترجیح دهید
INPUT_MEDIA_WIDGET_HTML_INVALIDUTF-8 نامعتبر یا کاراکتر NUL در HTMLفایل را به صورت متن UTF-8 بخوانید و به شکل رشته بفرستید
INPUT_MEDIA_WIDGET_DATA_TOO_LARGEchat_data یا public_data بیش از 1024 بایتکلیدهای کوتاه، JSON فشرده (separators=(",", ":"))؛ هر حرف فارسی 2 بایت است
message is not modifiedویرایش، همان وضعیت فعلی را تنظیم می‌کندموفقیت حساب کنید
query is too oldanswerWidgetQuery بعد از 15 ثانیهاول جواب دهید، کار کند را بعد انجام دهید
invalid cache time specifiedcache_time کمتر از 5مقدار 5 تا 3600 ثانیه

و در خود ویجت، code درخواست ردشده: NOT_ALLOWED (بدون allow_queries، بدون لمس، پیش‌نمایش یا فوروارد ویجت ثابت)، BUSY (فقط یک درخواست در هر لحظه)، RATE_LIMITED (بیش از 5 درخواست در 5 ثانیه)، TIMEOUT، FAILED و INVALID_ANSWER. داده خالی یا بلندتر از 64 بایت پیش از ارسال TypeError می‌دهد.

چک‌لیست قبل از ارسال ویجت برای کاربران

  1. حجم فشرده زیر 4096 بایت است (check_widget.py).
  2. ویجت با وضعیت null و بدون TelegramWidget هم چیز مفیدی رسم می‌کند.
  3. رنگ‌ها از متغیرهای --tg-theme-* می‌آیند و در تم روشن و تیره بررسی شده‌اند.
  4. پیام کپشن دارد؛ اعلان‌ها و اپ‌های قدیمی همین را نشان می‌دهند.
  5. ربات به هر widget_query ظرف 15 ثانیه جواب می‌دهد و allowed_updates شامل widget_query و shared_widget_query است.
  6. ویرایش‌ها سمت شما محدود شده‌اند و «message is not modified» خطا حساب نمی‌شود.

همه ویژگی‌ها، رویدادها و محدودیت‌های استفاده‌شده در مرجع API جاوااسکریپت TelegramWidget آمده‌اند و مستندات رسمی در core.telegram.org/bots/widgets است. برای پارامترهای همه متدها هم مرجع متدهای Bot API را ببینید.

پرسش‌های متداول

HTML را چطور به متد sendWidget بفرستم؟

کل سند را به صورت رشته در پارامتر html بگذارید و درخواست را JSON بفرستید؛ مثلاً در پایتون requests.post(url, json={"chat_id": 123456789, "html": html}) تا نقل‌قول‌ها و خط‌های جدید HTML درست کدگذاری شوند.

چرا ویجت بعد از لمس TIMEOUT نشان می‌دهد؟

ربات ظرف 15 ثانیه answerWidgetQuery را صدا نزده است. معمولاً ربات اجرا نیست یا allowed_updates را بدون widget_query (و shared_widget_query) می‌فرستد و اصلاً کوئری را دریافت نمی‌کند.

با خطای message is not modified در editMessageWidgetData چه کنم؟

آن را موفقیت حساب کنید: ویجت همین حالا همان وضعیت را دارد. این خطا وقتی می‌آید که chat_data یا public_data جدید با فعلی برابر باشد. کوئری‌ای را که باعث ویرایش شده هم حتماً جواب دهید.

چطور با ویجت اشتراکی تلگرام نظرسنجی زنده بسازم؟

ویجت را یک بار با is_shared و allow_queries بفرستید، widget.id را ذخیره کنید، آن را با sendSharedWidget به چت‌های دیگر بفرستید، رأی‌ها را بر اساس جفت (widget_id، from.id) بشمارید و جمع را حداکثر یک بار در ثانیه با editSharedWidgetData بنویسید. ویجت باید watchPublicData() را صدا بزند.

چطور ویجت را در مرورگر پیش‌نمایش کنم؟

بیرون از تلگرام window.TelegramWidget وجود ندارد، پس یک شیء جایگزین کوچک و متغیرهای تم را در فایل پیش‌نمایش جداگانه بالای کد ویجت بگذارید. مرورگر پروفایل و محدودیت‌های ویجت را اعمال نمی‌کند، پس قبل از ارسال برای کاربران، در خود تلگرام تست کنید.

ساخت ربات تلگرام: آموزش قدم‌به‌قدم از BotFather تا اولین پیام با Python

ساخت ربات تلگرام قدم‌به‌قدم: ساخت ربات در BotFather، گرفتن توکن، تست با getMe، پیدا کردن chat id و ارسال اولین پیام با curl و Python.

ارسال پیام با ربات تلگرام از طریق API تلگرام (sendMessage)

آموزش ارسال پیام با ربات تلگرام از طریق API تلگرام: متد sendMessage با curl، Python و JavaScript، قالب‌بندی HTML و MarkdownV2، دکمه شیشه‌ای و رفع خطاها.

توکن ربات تلگرام: چیست، چطور بگیریم، بررسی و باطل کنیم

توکن ربات تلگرام چیست و از کجا بگیریم؟ گرفتن توکن از BotFather، پیدا کردن توکن ربات قبلی، تست با getMe، باطل کردن توکن لو رفته و نگهداری امن آن.

وب هوک ربات تلگرام: راه‌اندازی setWebhook، بررسی و رفع خطا

آموزش ست وب هوک تلگرام با setWebhook: پیش‌نیازهای HTTPS و پورت‌ها، secret_token، بررسی با getWebhookInfo، حذف وب هوک و رفع خطاهای رایج مثل 409.

چت آیدی تلگرام: چیست، کجاست و چطور chat id کاربر، گروه و کانال را پیدا کنیم

چت آیدی تلگرام کجاست؟ پیدا کردن chat_id کاربر، گروه، سوپرگروه، کانال و تاپیک با getUpdates، معنی آیدی‌های منفی و رفع مشکل نتیجه خالی و خطای 409.

سرور تست تلگرام: چطور ربات را در محیط تست تلگرام تست کنیم

سرور تست تلگرام برای ربات‌ها: ورود به محیط تست، ساخت ربات تست در BotFather، فراخوانی Bot API با مسیر /test/ و سوییچ TEST در تستر ما.

ویجت تلگرام برای سایت: ورود با تلگرام، جاسازی پست، کامنت‌ها و دکمه اشتراک‌گذاری

ورود با تلگرام در سایت با Telegram Login (OIDC) و ویجت قدیمی همراه کد بررسی hash، جاسازی پست کانال، ویجت کامنت و دکمه اشتراک‌گذاری تلگرام.

مرجع API جاوااسکریپت TelegramWidget: رویدادها، کدهای خطا و محدودیت‌ها

مرجع API جاوااسکریپت ویجت تلگرام: ویژگی‌ها، request()، رویدادها، کدهای خطا، متغیرهای CSS، widget_query و answerWidgetQuery و همه محدودیت‌ها.

ویجت تلگرام چیست؟ HTML تعاملی داخل پیام‌های ربات

ویجت تلگرام در Bot API 10.4 چیست؟ ارسال با sendWidget، وضعیت chat_data و public_data، محدودیت‌ها، جاهایی که فعلاً کار می‌کند و تفاوت با مینی اپ.