텔레그램 위젯 예제: HTML과 Python 봇 코드 전체 공개
이 글의 텔레그램 위젯 예제는 모두 그대로 실행할 수 있습니다. 예제마다 위젯 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 기준" 식으로 조용히 바뀝니다. 위젯 수정에는 "수정됨" 표시도 알림도 없습니다. "기준" 시각을 붙인 이유는, 상태가 누군가 기다리는 진행 표시가 아니라 특정 시점의 스냅숏으로 읽히게 하기 위해서입니다.
editMessageWidgetData한 번은 봇의 메시지 전송 한도에서 메시지 하나로 계산되므로, 짧은 루프로 상태를 갱신하지 마십시오.- 위젯을 보낸 봇만 상태를 바꿀 수 있고, HTML 자체는 절대 교체할 수 없습니다.
예제 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>
위젯 코드의 핵심은 다음과 같습니다.
request()는 클릭 핸들러 안에서 동기적으로 호출합니다.await뒤나 타이머에서 나중에 호출하면NOT_ALLOWED로 거부됩니다. 탭 한 번에 호출 한 번입니다.- Promise는 봇의
data또는null을 담은{ result }로 resolve되고, 실패하면WidgetRequestError로 reject되며 그code를 사용자에게 보여 줍니다. - 텔레그램 밖에서는
window.TelegramWidget이undefined이므로 사용 전에W를 확인합니다.
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를 보내라고 안내합니다. 실제 봇이라면 상태를 채팅과 메시지 기준으로 데이터베이스에 저장하십시오.
- 응답하지 않은 요청은 위젯에서
TIMEOUT으로 끝나므로, 봇은 모르는 요청까지 모든 요청에 응답합니다. - 새 숫자는
editMessageWidgetData가 성공한 뒤에만 반영하고, "message is not modified"(예: 이미 0인 카운터에서 초기화)는 성공으로 봅니다. - 요청에는 위젯의 상태가 담겨 오지 않습니다. 기준은 봇이 가진 사본이며,
data는callback_data처럼 허용된 값 목록과 대조합니다.
예제 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초 정도 안에 나타납니다.
- 리비전
r이 필요한 이유: 공유 상태를 가져올 때 방금 응답으로 받은 상태보다 오래된 값이 올 수 있습니다. 위젯은 지금까지 본 가장 새로운r보다 낮은 상태를 무시합니다. - 초당 1회 수정: 공유 위젯은 초당 최대 한 번만 수정할 수 있고, 넘으면 flood wait 오류가 납니다. 봇은 상태를 dirty로 표시해 두었다가
flush()에서 기록하며, 기록할 것이 남아 있는 동안에는timeout=1로 폴링합니다. - 사용자당 한 표: 표는 이
widget_id에 대해from.id를 키로 저장합니다. 두 값 모두 텔레그램이 채우므로 위젯이 위조할 수 없습니다. shared_widget_query도 이미allowed_updates에 들어 있습니다. 전달 기능이 운영 환경에 열리면, 전달된 복사본에서 온 표(id,from,data,widget_id만 담김)도 같은 코드로 처리됩니다.- 실시간 시세 표시기는 요청이 없는 같은 패턴입니다.
allow_queries없이is_shared로 보내고, 루프에서 새 가격으로editSharedWidgetData를 호출하면 됩니다.
예제 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_LARGE | HTML이 32768바이트 또는 압축 후 4096바이트 초과 | 주석과 쓰지 않는 코드를 지우고, data: 이미지보다 SVG와 CSS를 씁니다 |
INPUT_MEDIA_WIDGET_HTML_INVALID | 잘못된 UTF-8 또는 HTML 안의 NUL 문자 | 파일을 UTF-8 텍스트로 읽어 문자열로 보냅니다 |
INPUT_MEDIA_WIDGET_DATA_TOO_LARGE | chat_data나 public_data가 1024바이트 초과 | 짧은 키, 간결한 JSON(separators=(",", ":"))을 씁니다. 한글은 글자당 3바이트입니다 |
message is not modified | 이미 같은 상태로 수정하려 함 | 성공으로 처리합니다 |
query is too old | 15초가 지난 뒤 answerWidgetQuery 호출 | 먼저 응답하고 오래 걸리는 작업은 그 뒤에 합니다 |
invalid cache time specified | cache_time이 5 미만 | 5~3600초로 지정합니다 |
위젯 쪽에서 거부된 요청의 code는 다음 중 하나입니다: NOT_ALLOWED(allow_queries 없음, 탭 없음, 미리보기, 정적 위젯의 전달본), BUSY(요청은 한 번에 하나), RATE_LIMITED(5초에 5회 초과), TIMEOUT, FAILED, INVALID_ANSWER. 데이터가 비어 있거나 64바이트를 넘으면 전송 전에 TypeError가 발생합니다.
사용자에게 위젯을 보내기 전 체크리스트
- 압축 크기가 4096바이트 미만인지 확인합니다(
check_widget.py). - 상태가
null일 때와TelegramWidget이 없을 때도 쓸모 있는 화면이 그려지는지 확인합니다. - 색상은
--tg-theme-*변수에서 가져오고, 밝은 테마와 어두운 테마에서 모두 확인합니다. - 메시지에 캡션이 있는지 확인합니다. 알림과 구버전 앱에는 캡션이 표시됩니다.
- 봇이 모든
widget_query에 15초 안에 응답하고,allowed_updates에widget_query와shared_widget_query가 들어 있는지 확인합니다. - 수정 빈도를 봇 쪽에서 제한하고, "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과의 차이를 정리했습니다.