Telegram Bot API

텔레그램 위젯 예제: HTML과 Python 봇 코드 전체 공개

· 13 분 분량

이 글의 텔레그램 위젯 예제는 모두 그대로 실행할 수 있습니다. 예제마다 위젯 HTML(압축 후 4KB 제한보다 훨씬 작음), requests와 롱 폴링으로 만든 Python 봇 코드, 사용자에게 보이는 화면 설명이 들어 있습니다. 정적 주문 카드로 시작해 카운터로 요청을 붙이고, 마지막으로 공유 위젯으로 실시간 투표를 만듭니다. 위젯이 처음이라면 텔레그램 위젯이란을 먼저 읽어 보십시오.

시작하기 전에: 운영 환경에서 위젯은 현재 봇과의 개인 채팅에서만 동작하며, 보호된 콘텐츠로 전송되어 전달할 수 없습니다. 그룹, 인라인 모드, 전달은 테스트 서버에서만 동작합니다. 아래 예제는 모두 개인 채팅에서 실행됩니다.

준비물: requests가 설치된 Python 3(pip install requests), 봇 토큰(텔레그램 봇 토큰 받는 법), 내 chat id. 각 위젯은 봇 스크립트와 같은 폴더에 파일로 저장합니다. 코드를 쓰기 전에 위젯 HTML을 Bot API Tester의 sendWidget 폼에 붙여 넣어 내 채팅에서 먼저 확인해 볼 수도 있습니다.

예제 1: 정적 주문 카드 (요청 없음)

주문이 진행될 때마다 봇이 상태 줄을 갱신하는 주문 요약 카드입니다. 위젯은 봇에 아무것도 묻지 않으므로 allow_queries 없이 보냅니다. 상태는 chat_data에 있고, 위젯은 시작할 때와 chatDataChanged 이벤트가 올 때마다 이를 그립니다. 메시지에는 캡션과 위젯 아래 인라인 키보드도 붙어 있습니다.

order.html (933바이트, 압축 후 576바이트):

<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"과 "주문 조회" 버튼이 있습니다. 1분마다 상태 줄이 "조리 중"과 회색 "19:40 기준" 식으로 조용히 바뀝니다. 위젯 수정에는 "수정됨" 표시도 알림도 없습니다. "기준" 시각을 붙인 이유는, 상태가 누군가 기다리는 진행 표시가 아니라 특정 시점의 스냅숏으로 읽히게 하기 위해서입니다.

예제 2: widget_query 요청을 쓰는 카운터

+1과 초기화 버튼이 있는 카운터입니다. 탭하면 TelegramWidget.request()가 호출되고, 봇은 숫자를 갱신해 editMessageWidgetData로 chat_data에 쓴 다음, 같은 값을 answerWidgetQuery로 응답해 위젯이 즉시 표시할 수 있게 합니다. 리비전 번호 r은 새 상태 뒤에 늦게 도착한 옛 상태를 위젯이 무시하도록 해 줍니다.

counter.html (1254바이트, 압축 후 753바이트):

<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: 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": 숫자, "r": 리비전}


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"):
        # 모르는 메시지(예: 봇 재시작) 또는 모르는 data: 그래도 응답한다
        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: 숫자, r: 리비전}

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)) {
    // 모르는 메시지(예: 봇 재시작) 또는 모르는 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)가 표시됩니다. 봇을 재시작하면 메모리의 딕셔너리가 비므로 봇은 data 없이 응답하고, 위젯은 /start를 보내라고 안내합니다. 실제 봇이라면 상태를 채팅과 메시지 기준으로 데이터베이스에 저장하십시오.

예제 3: 텔레그램 공유 위젯으로 만드는 실시간 투표

여러 개인 채팅에 표시되지만 결과는 하나인 투표입니다. is_shared와 allow_queries를 지정한 첫 sendWidget이 공유 위젯을 만들고, 봇은 반환된 메시지에서 widget.id를 저장한 뒤 /start를 보낸 모든 사용자에게 sendSharedWidget으로 같은 투표를 보냅니다. 표는 editSharedWidgetData로 public_data에 기록되므로 투표를 표시하는 모든 메시지가 새 합계를 받습니다.

poll.html (1842바이트, 압축 후 1065바이트):

<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: 사용자별로 표를 기록하고, 수정은 초당 1회로 모아서 보냅니다.

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: 사용자 id -> 선택지
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():
    """공유 상태는 초당 최대 1회만 기록한다(공유 위젯 제한)."""
    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: 사용자 id -> 선택지
}
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 });
}

// 공유 상태는 초당 최대 1회만 기록한다(공유 위젯 제한).
async function flush() {
  const now = performance.now() / 1000; // 단조 증가하는 초 단위 시각
  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~430px의 데스크톱 브라우저 창에서 먼저 대략 확인할 수 있습니다. 텔레그램 밖에는 TelegramWidget이 없으니 위젯 코드 위에 대체 객체를 넣습니다. 보내는 HTML에 섞이지 않도록 별도 파일 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는 대체 객체와 위젯을 이어 붙여 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("너비 320-430px 브라우저 창에서 preview.html을 여세요")
// 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("너비 320-430px 브라우저 창에서 preview.html을 여세요");

python3 preview.py counter.html을 실행하고 preview.html을 연 뒤, 콘솔에 request like가 찍히는지 확인합니다. chatData, publicData, viewer, isForward를 바꿔 가며 보고 싶은 경우를 재현하십시오. 브라우저는 텔레그램이 제거하는 요소(input, vh, 스크롤)도 그대로 그리고 제한도 전혀 적용하지 않는다는 점을 기억하십시오.

check_widget.py는 보내기 전에 서버와 똑같은 방식(Python zlib 레벨 9)으로 크기를 잽니다. JavaScript 프로젝트에서는 Node.js 버전이 편리하지만, Node의 zlib는 결과가 몇 바이트 다를 수 있으므로 4096에 가까울 때는 Python 결과를 믿으십시오.

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 문자: 서버가 INPUT_MEDIA_WIDGET_HTML_INVALID를 반환합니다")
if len(raw) > 32768 or packed > 4096:
    sys.exit("너무 큼: 서버가 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 발생
// Node에 포함된 zlib는 서버(Python)와 몇 바이트 다를 수 있으므로
// 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 문자: 서버가 INPUT_MEDIA_WIDGET_HTML_INVALID를 반환합니다");
}
if (raw.length > 32768 || packed > 4096) {
  fail("너무 큼: 서버가 INPUT_MEDIA_WIDGET_TOO_LARGE를 반환합니다");
}
console.log("OK");
$ python3 check_widget.py counter.html
1254 bytes, 753 bytes after zlib level 9
OK

이 예제를 다루면서 Bot API에서 만날 수 있는 오류는 다음과 같습니다.

오류원인해결
INPUT_MEDIA_WIDGET_TOO_LARGEHTML이 32768바이트 또는 압축 후 4096바이트 초과주석과 쓰지 않는 코드를 지우고, data: 이미지보다 SVG와 CSS를 씁니다
INPUT_MEDIA_WIDGET_HTML_INVALID잘못된 UTF-8 또는 HTML 안의 NUL 문자파일을 UTF-8 텍스트로 읽어 문자열로 보냅니다
INPUT_MEDIA_WIDGET_DATA_TOO_LARGEchat_data나 public_data가 1024바이트 초과짧은 키, 간결한 JSON(separators=(",", ":"))을 씁니다. 한글은 글자당 3바이트입니다
message is not modified이미 같은 상태로 수정하려 함성공으로 처리합니다
query is too old15초가 지난 뒤 answerWidgetQuery 호출먼저 응답하고 오래 걸리는 작업은 그 뒤에 합니다
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"를 오류로 처리하지 않는지 확인합니다.

여기서 쓴 속성, 이벤트, 제한은 모두 TelegramWidget JavaScript API 레퍼런스에 정리되어 있으며, 공식 문서는 core.telegram.org/bots/widgets에 있습니다. 봇을 아직 만들지 않았다면 텔레그램 봇 만들기부터 시작하십시오.

자주 묻는 질문

sendWidget에 HTML은 어떻게 넘기나요?

문서 전체를 문자열 파라미터 html로 넘깁니다. Python이라면 requests.post(url, json={"chat_id": 123456789, "html": html})처럼 JSON으로 보내야 HTML 안의 따옴표와 줄바꿈이 올바르게 인코딩됩니다.

위젯을 탭하면 TIMEOUT이 표시됩니다. 왜 그런가요?

봇이 15초 안에 answerWidgetQuery를 호출하지 않았기 때문입니다. 대개 봇이 실행 중이 아니거나, allowed_updates에 widget_query(와 shared_widget_query)를 넣지 않아 요청 자체를 받지 못하는 경우입니다.

editMessageWidgetData가 "message is not modified"를 반환하면 어떻게 하나요?

성공으로 처리하십시오. 새 chat_data나 public_data가 현재 값과 같을 때 나는 오류로, 위젯은 이미 그 상태입니다. 수정을 일으킨 위젯 요청에는 그래도 응답해야 합니다.

텔레그램 공유 위젯으로 실시간 투표를 만들려면?

is_shared와 allow_queries로 위젯을 한 번 보내고 widget.id를 저장한 뒤, 다른 채팅에는 sendSharedWidget으로 보냅니다. 표는 (widget_id, from.id) 단위로 세고, 합계는 초당 1회 이하로 editSharedWidgetData에 씁니다. 위젯은 watchPublicData()를 호출해야 합니다.

브라우저에서 위젯을 미리 볼 수 있나요?

텔레그램 밖에서는 window.TelegramWidget이 없으므로, 별도의 미리보기 파일에서 위젯 코드 위에 간단한 대체 객체와 테마 변수를 넣으면 됩니다. 브라우저는 위젯 프로필과 제한을 적용하지 않으므로 사용자에게 보내기 전에 반드시 텔레그램에서 확인하십시오.

텔레그램 봇 만들기: @BotFather로 생성하고 첫 메시지 보내기

텔레그램 봇 만들기 가이드입니다. @BotFather의 /newbot으로 봇을 생성하고 토큰을 getMe로 확인한 뒤, getUpdates와 sendMessage로 첫 메시지를 보내는 과정을 curl과 Python 예제로 설명합니다.

텔레그램 봇 API로 메시지 보내기: sendMessage 사용법과 예제

텔레그램 봇 API 메시지 보내기 가이드입니다. sendMessage를 curl·Python·JavaScript로 호출하는 예제, HTML·MarkdownV2 서식, 인라인 버튼, 그룹·채널 전송, 400·403·429 오류 해결법을 정리했습니다.

텔레그램 봇 토큰: 발급부터 확인, 폐기, 안전한 보관까지

텔레그램 봇 토큰을 @BotFather에서 발급받는 법, 기존 봇의 토큰 찾기, getMe로 유효성 확인, 유출 시 폐기 방법을 정리했습니다. n8n·AI 비서 연동에 필요한 bot token과 chat id도 안내합니다.

텔레그램 웹훅 설정 가이드: setWebhook, secret_token, getWebhookInfo

텔레그램 봇 웹훅 설정 방법을 단계별로 정리했습니다. setWebhook 파라미터, secret_token 헤더 검증 코드, getWebhookInfo 상태 확인, deleteWebhook으로 되돌리기, 409·HTTPS 오류 해결까지 다룹니다.

텔레그램 chat id 확인방법: 개인, 그룹, 채널, 토픽별 chat id 찾기

텔레그램 chat id 확인방법을 개인 채팅, 그룹, 슈퍼그룹, 채널, 포럼 토픽별로 정리했습니다. getUpdates로 chat id를 찾는 법, -100으로 시작하는 ID의 의미, 결과가 비어 있을 때 해결법까지 설명합니다.

텔레그램 테스트 서버: 텔레그램 봇 테스트 환경에서 봇을 테스트하는 방법

텔레그램 테스트 서버 사용법을 정리했습니다. 테스트 환경 로그인, 테스트용 봇 만들기, /test/ 주소로 Bot API 호출하기, Bot API Tester의 TEST 스위치까지 다룹니다.

텔레그램 웹사이트 위젯: 로그인 위젯, 게시물 임베드, 댓글, 공유 버튼

웹사이트에 텔레그램을 붙이는 방법을 정리했습니다. 새 Telegram Login(OIDC), 기존 로그인 위젯과 hash 검증 코드, 게시물 임베드, 댓글, 공유 버튼까지 다룹니다.

TelegramWidget JavaScript API: 텔레그램 위젯 API 레퍼런스와 오류 코드, 제한

텔레그램 위젯의 TelegramWidget JavaScript API를 정리했습니다. 속성, request(), 이벤트, 오류 코드, CSS 변수, widget_query와 answerWidgetQuery, 모든 제한값까지 담았습니다.

텔레그램 위젯 가이드: 봇 메시지 안에서 동작하는 HTML 위젯

Bot API 10.4에 추가된 텔레그램 위젯의 개념, sendWidget 사용법, chat_data와 public_data, 현재 사용 가능한 범위와 Mini App과의 차이를 정리했습니다.