Telegram Bot API

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

· 9 분 분량

텔레그램 위젯은 봇이 sendWidget 메서드로 메시지 안에 넣어 보내는 작은 인터랙티브 HTML 블록으로, 2026년 11월 9일 Bot API 10.4에서 추가되었습니다. 위젯은 최대 32KB의 HTML 문서 하나이며, 텔레그램 앱이 사용자 기기에서 네트워크 없이 실행하고 채팅 스타일에 맞춰 그려 줍니다. 상태가 바뀌는 주문 카드, 카운터, 투표할 때마다 막대가 움직이는 설문, 한 번 탭하면 복사되는 프로모 코드 같은 것을 텔레그램 봇 위젯으로 만들 수 있습니다.

현재 위젯을 쓸 수 있는 곳: 운영(production) 환경에서는 봇이 사용자와의 개인 채팅에만 위젯을 보낼 수 있고, 메시지가 보호된 콘텐츠로 전송되어 전달(forward)할 수 없습니다. 그룹, 인라인 모드, 전달된 위젯은 지금은 테스트 서버에서만 동작합니다.

텔레그램 위젯이란

코드와 상태: chat_data와 public_data

위젯은 고정된 코드 + 바뀌는 상태입니다. HTML은 전송할 때 정해지고 이후 어떤 메서드로도 교체할 수 없습니다. 바뀌는 것은 상태뿐이고, 상태는 봇만 씁니다. 위젯은 이를 TelegramWidget.chatData와 TelegramWidget.publicData로 읽고, chatDataChanged·publicDataChanged 이벤트가 오면 다시 그립니다.

항목채팅 상태 (chat_data)공유 상태 (public_data)
연결 대상원본 메시지 하나정적 위젯의 메시지, 또는 공유 위젯이 표시되는 모든 곳
보이는 곳해당 채팅에서만 (그룹에서는 모든 멤버가 같은 값)위젯이 표시되는 모든 곳
전달된 메시지에서절대 전달되지 않음복사본(정적 위젯) 또는 실시간 공유 상태(공유 위젯)
크기최대 1024바이트 텍스트최대 1024바이트 텍스트
변경 방법editMessageWidgetDataeditMessageWidgetData 또는 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, 전송 후 고정
엔진플랫폼의 WebViewQuickJS 샌드박스, 텔레그램 앱이 그림
네트워크웹 전체없음
봇과의 통신서명된 initData와 내 백엔드TelegramWidget.request() → widget_query 업데이트
입력키보드를 포함한 모든 입력탭과 포인터 이벤트, 키보드 없음

두 API가 겹치는 부분에서 TelegramWidget은 Telegram.WebApp과 같은 이름(themeParams, colorScheme, onEvent, openLink, HapticFeedback, ready)을 씁니다. 위젯에 담기 어려운 큰 기능은 openTelegramLink로 봇이나 Mini App을 열어 처리하십시오. Mini App을 만들고 있다면 브라우저에서 바로 써 볼 수 있는 Mini App Tester가 도움이 됩니다.

sendWidget으로 첫 텔레그램 위젯 보내기

  1. 봇을 만들고 토큰을 복사합니다(텔레그램 봇 만들기, 텔레그램 봇 토큰 확인하기).
  2. 봇이 나에게 메시지를 보낼 수 있도록 봇에 /start를 보내고, getUpdates에서 chat id를 확인합니다.
  3. 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" 필드가 담긴 전송된 Message
const 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" 필드가 담긴 전송된 Message

CSS가 한 줄도 없지만 이 위젯은 일반 메시지처럼 보이고 버튼도 네이티브 모양으로 그려집니다. 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)은 위젯 안의 콜백 버튼처럼 동작합니다.

  1. 봇이 allow_queries: true로 위젯을 보냅니다.
  2. 사용자가 탭하면 위젯이 1~64바이트 데이터로 TelegramWidget.request("like")를 호출합니다.
  3. 봇은 id, from, chat, message_id, data가 담긴 widget_query 업데이트를 받습니다(공유 위젯이 전달된 메시지에서 오면 shared_widget_query). allowed_updates를 지정한다면 두 종류를 모두 넣어야 합니다.
  4. 봇은 15초 안에 answerWidgetQuery를 호출합니다. 선택적으로 최대 1024바이트의 data를 넘길 수 있으며, 이 값은 요청한 위젯만 받습니다.
  5. 모두에게 보이는 내용을 바꾸려면 editMessageWidgetData(또는 editSharedWidgetData)를 호출합니다. 위젯은 chatDataChanged·publicDataChanged를 받습니다.

응답 자체는 상태를 바꾸지 않습니다. 요청은 사용자·봇 쌍마다 5초에 5회로 제한되고, 응답하지 않으면 위젯에서 TIMEOUT으로 끝납니다. 실제로 동작하는 전체 코드는 텔레그램 위젯 예제에 있습니다.

정적 위젯과 공유 위젯

is_shared 없이 보내면 정적 위젯입니다. 코드와 상태가 메시지 안에 있고, 전달하면 그 시점의 고정된 복사본이 됩니다. is_shared를 지정하면 첫 전송이 공유 위젯을 만듭니다. 공유 위젯은 식별자(반환된 메시지의 widget.id)를 가진 하나의 객체이며, 여러 메시지가 같은 위젯을 표시할 수 있습니다. sendSharedWidget으로 다시 보내고, editSharedWidgetData로 모든 메시지의 공유 상태를 한 번에 바꿉니다(초당 최대 1회). 이미 화면에 떠 있는 위젯은 TelegramWidget.watchPublicData()를 호출해야 새 공유 상태를 받으며, 앱은 위젯의 갱신 주기(기본 30초, cache_time으로 5~3600초)마다 상태를 가져옵니다.

텔레그램 위젯 제한 요약

항목제한
HTML32768바이트, zlib 레벨 9 압축 후 4096바이트
chat_data, public_data각 1024바이트
요청 데이터 / 응답 데이터1~64바이트 / 최대 1024바이트
요청 응답 시간15초
요청 횟수사용자·봇 쌍마다 5초에 5회
말풍선 크기너비 200px~말풍선 최대 너비, 높이 50~600px, 넘치는 부분은 잘림
공유 위젯 수정초당 1회
메모리 / DOM 노드8MB / 2000개

CPU 할당량, 타이머, 스토리지까지 포함한 전체 표는 TelegramWidget API 레퍼런스에 있습니다.

위젯 디자인 팁

웹사이트용 텔레그램 위젯과 혼동하지 마세요

"텔레그램 위젯"은 예전부터 있던 웹사이트용 위젯, 즉 Telegram Login Widget, 게시물 임베드, 공유 버튼을 가리키기도 합니다. 이것들은 내 사이트에 넣는 스크립트입니다. Bot API 10.4의 위젯은 봇이 채팅으로 보내는 HTML로, 전혀 다른 기능입니다. 사이트에 로그인 위젯이나 게시물 임베드를 넣는 방법은 텔레그램 웹사이트 위젯 가이드에 정리했습니다. 공식 문서는 core.telegram.org/bots/widgets에 있습니다.

다음 단계

자주 묻는 질문

텔레그램 위젯이란 무엇인가요?

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 코드로 설명합니다.