텔레그램 위젯 가이드: 봇 메시지 안에서 동작하는 HTML 위젯
텔레그램 위젯은 봇이 sendWidget 메서드로 메시지 안에 넣어 보내는 작은 인터랙티브 HTML 블록으로, 2026년 11월 9일 Bot API 10.4에서 추가되었습니다. 위젯은 최대 32KB의 HTML 문서 하나이며, 텔레그램 앱이 사용자 기기에서 네트워크 없이 실행하고 채팅 스타일에 맞춰 그려 줍니다. 상태가 바뀌는 주문 카드, 카운터, 투표할 때마다 막대가 움직이는 설문, 한 번 탭하면 복사되는 프로모 코드 같은 것을 텔레그램 봇 위젯으로 만들 수 있습니다.
현재 위젯을 쓸 수 있는 곳: 운영(production) 환경에서는 봇이 사용자와의 개인 채팅에만 위젯을 보낼 수 있고, 메시지가 보호된 콘텐츠로 전송되어 전달(forward)할 수 없습니다. 그룹, 인라인 모드, 전달된 위젯은 지금은 테스트 서버에서만 동작합니다.
텔레그램 위젯이란
- HTML 문서 하나.
<style>과<script>는 인라인으로 넣고, 이미지는data:URL이나 인라인 SVG만 씁니다. UTF-8 기준 최대 32768바이트, zlib 레벨 9 압축 후 최대 4096바이트입니다.<html>·<body>없는 조각만 보내도 됩니다. - 샌드박스 실행. JavaScript는 WebView가 아니라 소형 JavaScript 엔진인 QuickJS에서 실행됩니다. 앱은 위젯이 페이지에 가하는 모든 변경을 위젯 프로필에 비추어 검사하고 통과한 것만 그리므로, iOS, Android, macOS, Telegram Desktop, 웹에서 똑같이 보입니다.
- 오프라인.
fetch,XMLHttpRequest,WebSocket등 네트워크 API는NetworkDisabledError를 던집니다. 외부 스크립트, 스타일, 폰트, 이미지는 로드되지 않고 번들된 라이브러리도 없습니다. - 네이티브한 모양. 채팅 팔레트를
--tg-theme-*CSS 변수로 쓸 수 있고, 스타일을 주지 않은<button>은 앱 자체 버튼처럼 그려집니다. - 키보드 없음. input, select, textarea는 제거됩니다. 위젯은 탭, 포인터 이벤트, 가로 드래그, 길게 누르기에 반응합니다.
코드와 상태: chat_data와 public_data
위젯은 고정된 코드 + 바뀌는 상태입니다. HTML은 전송할 때 정해지고 이후 어떤 메서드로도 교체할 수 없습니다. 바뀌는 것은 상태뿐이고, 상태는 봇만 씁니다. 위젯은 이를 TelegramWidget.chatData와 TelegramWidget.publicData로 읽고, chatDataChanged·publicDataChanged 이벤트가 오면 다시 그립니다.
| 항목 | 채팅 상태 (chat_data) | 공유 상태 (public_data) |
|---|---|---|
| 연결 대상 | 원본 메시지 하나 | 정적 위젯의 메시지, 또는 공유 위젯이 표시되는 모든 곳 |
| 보이는 곳 | 해당 채팅에서만 (그룹에서는 모든 멤버가 같은 값) | 위젯이 표시되는 모든 곳 |
| 전달된 메시지에서 | 절대 전달되지 않음 | 복사본(정적 위젯) 또는 실시간 공유 상태(공유 위젯) |
| 크기 | 최대 1024바이트 텍스트 | 최대 1024바이트 텍스트 |
| 변경 방법 | editMessageWidgetData | editMessageWidgetData 또는 editSharedWidgetData |
| 예 | 진행 중인 게임, 주문 상태 | 투표 결과, 가격 |
두 상태 모두 서버가 해석하지 않는 일반 텍스트이며 보통 JSON을 씁니다. 1024바이트는 문자 수가 아니라 UTF-8 바이트 수이므로 한글은 한 글자에 3바이트를 차지합니다. 위젯 안에서 상태가 없거나 지워진 경우 값은 null입니다.
위젯이 동작하는 곳: 운영 환경과 테스트 서버
| 위치 | 보내는 방법 | 요청 (allow_queries 사용 시) | 운영 환경 |
|---|---|---|---|
| 봇과의 개인 채팅 | sendWidget, sendSharedWidget | 탭할 때와 백그라운드 | 지원 |
| 일반 그룹·슈퍼그룹 | sendWidget | 탭할 때만 | 테스트 서버만 |
| 채널을 제외한 모든 채팅(봇을 통해) | 인라인 모드 (InputWidgetMessageContent, InputSharedWidgetMessageContent) | 탭할 때만 | 테스트 서버만 |
| 전달된 메시지(채널 포함) | 사용자가 전달 | 탭할 때, 공유 위젯만 | 테스트 서버만 |
봇은 채널에 위젯을 올릴 수 없습니다. 위젯을 지원하지 않는 앱에서는 메시지가 캡션과 함께 지원되지 않는 미디어로 표시됩니다. 위젯 메시지는 copyMessage·copyMessages로 복사할 수 없고, 그룹에서는 can_send_other_messages 권한이 위젯 전송도 포함합니다.
텔레그램 위젯과 Mini App 비교
| 항목 | Mini App | 위젯 |
|---|---|---|
| 위치 | 버튼, 메뉴, 링크로 여는 WebView | 메시지 말풍선 안, 채팅에서 항상 보임 |
| 코드 | 내 서버의 웹 페이지 | 메시지에 담긴 최대 32KB HTML, 전송 후 고정 |
| 엔진 | 플랫폼의 WebView | QuickJS 샌드박스, 텔레그램 앱이 그림 |
| 네트워크 | 웹 전체 | 없음 |
| 봇과의 통신 | 서명된 initData와 내 백엔드 | TelegramWidget.request() → widget_query 업데이트 |
| 입력 | 키보드를 포함한 모든 입력 | 탭과 포인터 이벤트, 키보드 없음 |
두 API가 겹치는 부분에서 TelegramWidget은 Telegram.WebApp과 같은 이름(themeParams, colorScheme, onEvent, openLink, HapticFeedback, ready)을 씁니다. 위젯에 담기 어려운 큰 기능은 openTelegramLink로 봇이나 Mini App을 열어 처리하십시오. Mini App을 만들고 있다면 브라우저에서 바로 써 볼 수 있는 Mini App Tester가 도움이 됩니다.
sendWidget으로 첫 텔레그램 위젯 보내기
- 봇을 만들고 토큰을 복사합니다(텔레그램 봇 만들기, 텔레그램 봇 토큰 확인하기).
- 봇이 나에게 메시지를 보낼 수 있도록 봇에
/start를 보내고,getUpdates에서 chat id를 확인합니다. - sendWidget을 호출합니다.
html파라미터는 문자열이므로 요청은 JSON으로 보냅니다.
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendWidget" \
-H "Content-Type: application/json" \
-d '{
"chat_id": 123456789,
"html": "<h3>프로모 코드</h3><p>버튼을 누르면 복사됩니다.</p><button onclick=\"TelegramWidget.copyText(this.textContent)\">PROMO10</button>",
"caption": "프로모 코드: PROMO10"
}'
Python requests나 JavaScript fetch로 보내면 다음과 같습니다.
import requests
API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours"
html = """<h3>프로모 코드</h3>
<p>버튼을 누르면 복사됩니다.</p>
<button onclick="TelegramWidget.copyText(this.textContent)">PROMO10</button>"""
r = requests.post(f"{API}/sendWidget", json={
"chat_id": 123456789,
"html": html,
"caption": "프로모 코드: PROMO10",
}, timeout=10)
print(r.json()) # result: "widget" 필드가 담긴 전송된 Messageconst API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours";
const html = `<h3>프로모 코드</h3>
<p>버튼을 누르면 복사됩니다.</p>
<button onclick="TelegramWidget.copyText(this.textContent)">PROMO10</button>`;
const r = await fetch(`${API}/sendWidget`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
chat_id: 123456789,
html,
caption: "프로모 코드: PROMO10",
}),
signal: AbortSignal.timeout(10_000),
});
console.log(await r.json()); // result: "widget" 필드가 담긴 전송된 MessageCSS가 한 줄도 없지만 이 위젯은 일반 메시지처럼 보이고 버튼도 네이티브 모양으로 그려집니다. TelegramWidget은 script 태그 없이도 존재하며, copyText는 탭 핸들러 안에서 호출되었기 때문에 동작합니다. 같은 HTML을 Bot API Tester의 sendWidget 폼에 붙여 넣고 내 토큰으로 바로 보내 볼 수도 있습니다.
sendWidget의 다른 파라미터: width·height(논리 픽셀 단위 크기 기준값), chat_data·public_data(초기 상태), allow_queries, is_shared, 그리고 일반 메시지와 같은 캡션, reply_markup, reply_parameters, message_thread_id, protect_content입니다.
위젯이 봇과 통신하는 방법
요청(request)은 위젯 안의 콜백 버튼처럼 동작합니다.
- 봇이
allow_queries: true로 위젯을 보냅니다. - 사용자가 탭하면 위젯이 1~64바이트 데이터로
TelegramWidget.request("like")를 호출합니다. - 봇은
id,from,chat,message_id,data가 담긴widget_query업데이트를 받습니다(공유 위젯이 전달된 메시지에서 오면shared_widget_query).allowed_updates를 지정한다면 두 종류를 모두 넣어야 합니다. - 봇은 15초 안에 answerWidgetQuery를 호출합니다. 선택적으로 최대 1024바이트의
data를 넘길 수 있으며, 이 값은 요청한 위젯만 받습니다. - 모두에게 보이는 내용을 바꾸려면 editMessageWidgetData(또는
editSharedWidgetData)를 호출합니다. 위젯은chatDataChanged·publicDataChanged를 받습니다.
응답 자체는 상태를 바꾸지 않습니다. 요청은 사용자·봇 쌍마다 5초에 5회로 제한되고, 응답하지 않으면 위젯에서 TIMEOUT으로 끝납니다. 실제로 동작하는 전체 코드는 텔레그램 위젯 예제에 있습니다.
정적 위젯과 공유 위젯
is_shared 없이 보내면 정적 위젯입니다. 코드와 상태가 메시지 안에 있고, 전달하면 그 시점의 고정된 복사본이 됩니다. is_shared를 지정하면 첫 전송이 공유 위젯을 만듭니다. 공유 위젯은 식별자(반환된 메시지의 widget.id)를 가진 하나의 객체이며, 여러 메시지가 같은 위젯을 표시할 수 있습니다. sendSharedWidget으로 다시 보내고, editSharedWidgetData로 모든 메시지의 공유 상태를 한 번에 바꿉니다(초당 최대 1회). 이미 화면에 떠 있는 위젯은 TelegramWidget.watchPublicData()를 호출해야 새 공유 상태를 받으며, 앱은 위젯의 갱신 주기(기본 30초, cache_time으로 5~3600초)마다 상태를 가져옵니다.
텔레그램 위젯 제한 요약
| 항목 | 제한 |
|---|---|
| HTML | 32768바이트, zlib 레벨 9 압축 후 4096바이트 |
chat_data, public_data | 각 1024바이트 |
| 요청 데이터 / 응답 데이터 | 1~64바이트 / 최대 1024바이트 |
| 요청 응답 시간 | 15초 |
| 요청 횟수 | 사용자·봇 쌍마다 5초에 5회 |
| 말풍선 크기 | 너비 200px~말풍선 최대 너비, 높이 50~600px, 넘치는 부분은 잘림 |
| 공유 위젯 수정 | 초당 1회 |
| 메모리 / DOM 노드 | 8MB / 2000개 |
CPU 할당량, 타이머, 스토리지까지 포함한 전체 표는 TelegramWidget API 레퍼런스에 있습니다.
위젯 디자인 팁
- 캡션은 항상 넣습니다. 채팅 목록, 알림, 검색, 위젯을 지원하지 않는 앱에는 캡션이 표시됩니다.
- 테마를 따릅니다. 색상은
--tg-theme-*변수로 지정하고 밝은 테마와 어두운 테마에서 모두 확인하십시오.prefers-color-scheme는 시스템이 아니라 채팅 테마를 따릅니다. - 첫 화면은 바로 그립니다.
chatData·publicData로 즉시 렌더링하면 되고, 로드할 것은 없습니다. - 작게 유지합니다. 서버와 같은 방식으로 압축 크기를 재 보십시오:
python3 -c 'import sys,zlib; print(len(zlib.compress(sys.stdin.buffer.read(), 9)))' < widget.html - 비밀 정보는 넣지 않습니다. 코드와 공유 상태는 공개된 것으로 간주하십시오. 그룹에서는 모든 멤버가 채팅 상태를 봅니다.
- 너비 기준으로 배치합니다.
%, flex, grid를 쓰십시오.vh는 지원되지 않고 위젯 안에서는 스크롤도 되지 않습니다. - 요청의 모든 결과를 보여 줍니다. "전송 중…", 봇의 응답, 각 오류 코드를 사용자에게 표시하십시오.
웹사이트용 텔레그램 위젯과 혼동하지 마세요
"텔레그램 위젯"은 예전부터 있던 웹사이트용 위젯, 즉 Telegram Login Widget, 게시물 임베드, 공유 버튼을 가리키기도 합니다. 이것들은 내 사이트에 넣는 스크립트입니다. Bot API 10.4의 위젯은 봇이 채팅으로 보내는 HTML로, 전혀 다른 기능입니다. 사이트에 로그인 위젯이나 게시물 임베드를 넣는 방법은 텔레그램 웹사이트 위젯 가이드에 정리했습니다. 공식 문서는 core.telegram.org/bots/widgets에 있습니다.
다음 단계
- 텔레그램 위젯 예제: 주문 카드, 요청을 쓰는 카운터, 실시간 공유 투표를 Python 봇 코드와 함께 다룹니다.
- TelegramWidget JavaScript API: 속성, 메서드, 이벤트, 오류 코드, CSS 변수, 제한을 정리했습니다.
- Bot API 메서드 레퍼런스:
sendWidget을 비롯해 10.4에 추가된 메서드의 파라미터를 확인할 수 있습니다.
자주 묻는 질문
텔레그램 위젯이란 무엇인가요?
Bot API 10.4(2026년 11월 9일)에 추가된, 봇 메시지 안에 그려지는 작은 인터랙티브 블록입니다. 인라인 CSS와 JavaScript를 담은 HTML 문서 하나로 이루어지며, 텔레그램 앱이 사용자 기기의 샌드박스에서 네트워크 없이 실행합니다.
텔레그램 위젯을 그룹에서도 쓸 수 있나요?
운영 환경에서는 아직 안 됩니다. 현재 운영 환경의 봇은 사용자와의 개인 채팅에만 위젯을 보낼 수 있고, 위젯 메시지는 전달할 수 없습니다. 그룹, 인라인 모드, 전달은 테스트 서버에서만 동작합니다.
봇에서 위젯은 어떻게 보내나요?
chat_id와 html(문자열, 1~32768바이트, zlib 레벨 9 압축 후 4096바이트 이하)을 넘겨 sendWidget을 호출합니다. 필요하면 caption, chat_data, public_data, allow_queries를 함께 넘깁니다. 성공하면 widget 필드가 담긴 Message가 반환됩니다.
텔레그램 위젯에서 HTTP 요청을 보낼 수 있나요?
없습니다. fetch, XMLHttpRequest, WebSocket 등 모든 네트워크 API는 NetworkDisabledError를 던집니다. 외부와 통신하는 유일한 방법은 TelegramWidget.request()로, 1~64바이트를 봇에 widget_query 업데이트로 보냅니다.
위젯과 Mini App은 무엇이 다른가요?
Mini App은 직접 호스팅하는 웹 페이지를 버튼이나 링크로 WebView에 여는 방식이고 네트워크를 자유롭게 씁니다. 위젯은 메시지 말풍선 안에 있고, 전송 시점에 고정되는 32KB 이하의 HTML이며, 네트워크 없이 요청을 통해서만 봇과 통신합니다.
보낸 위젯의 HTML을 나중에 바꿀 수 있나요?
바꿀 수 없습니다. 코드는 전송 후 고정되고 상태만 바뀝니다. editMessageWidgetData나 editSharedWidgetData로 chat_data·public_data를 고치거나, 새 레이아웃이 필요하면 위젯을 새로 보내십시오. 캡션은 editMessageCaption으로 수정할 수 있습니다.
관련 가이드
텔레그램 봇 만들기: @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과 Python 봇 코드 전체 공개
바로 실행할 수 있는 텔레그램 위젯 예제 모음입니다. 정적 주문 카드, widget_query 카운터, 실시간 공유 투표, 브라우저 미리보기까지 HTML과 Python 코드로 설명합니다.