TelegramWidget JavaScript API: 텔레그램 위젯 API 레퍼런스와 오류 코드, 제한
텔레그램 위젯 API는 Bot API 10.4 위젯이 텔레그램 앱으로부터 받는 window.TelegramWidget 객체와, 봇 쪽의 widget_query 업데이트·answerWidgetQuery 메서드로 이루어집니다. 이 레퍼런스는 TelegramWidget의 모든 속성, 메서드, 이벤트, 오류 코드와 CSS 변수, 제스처 규칙, 제한값을 공식 텔레그램 위젯 문서를 바탕으로 정리한 것입니다.
사용 가능 범위: 운영 환경에서 위젯은 현재 봇과의 개인 채팅에서만 동작하며, 보호된 콘텐츠로 전송되어 전달할 수 없습니다. 그룹, 인라인 모드, 전달은 테스트 서버에서만 동작하므로isForward나chatType: "group"같은 속성은 우선 테스트 서버에서 의미가 있습니다.
위젯이 처음이라면 텔레그램 위젯이란과 텔레그램 위젯 예제부터 보십시오.
TelegramWidget 객체가 생기는 방식
위젯에는 script 태그가 필요 없습니다. 텔레그램 안에서는 위젯의 첫 스크립트가 실행되기 전에 window.TelegramWidget이 존재하고, 텔레그램 밖(일반 브라우저)에서는 undefined입니다. 프로필 안에서 나중에 추가된 메서드는 typeof로 확인합니다.
const W = window.TelegramWidget; // 일반 브라우저에서는 undefined
if (W && typeof W.setResizeAnchor === 'function') W.setResizeAnchor('bottom');
function render() {
let state = null;
try { state = JSON.parse(W.chatData); } catch (e) {}
// state로 화면을 그린다. null이면 "아직 상태 없음"
}
if (W) W.onEvent('chatDataChanged', render);
render();
TelegramWidget 속성
| 속성 | 타입 | 설명 |
|---|---|---|
profile | Integer | 앱이 적용하는 위젯 프로필. 현재 버전은 1 |
colorScheme | String | 채팅 색 구성 light 또는 dark (--tg-color-scheme와 같음) |
themeParams | Object | 말풍선 팔레트. Mini App의 themeParams와 같은 키에 #rrggbb 문자열 |
isActive | Boolean | 위젯이 화면에 보이는지 (!document.hidden) |
isPreview | Boolean | 전송 전 표시되는 인라인 결과 미리보기. 탭과 요청 불가 |
isForward | Boolean | 전달된 복사본인지 |
chatType | String | private, group, supergroup, channel. 전달본이나 미리보기에서는 null |
viewer | Object | 보고 있는 사용자의 id, first_name, last_name, username, is_premium. 요청을 보낼 수 있는 곳에서만 제공되고 그 밖에서는 null |
publicData | String | 공유 상태(최대 1024바이트) 또는 null. 읽기 전용 |
chatData | String | 채팅 상태(최대 1024바이트) 또는 null. 전달본에서는 항상 null. 읽기 전용 |
contentSafeAreaInset | Object | top, right, bottom, left, cornerLeft, cornerRight: 메시지 시각이 가리는 영역 |
wallet | Object | 텔레그램 지갑. 앱에 지갑이 없거나, 요청이 허용되지 않거나, 미리보기이면 null |
HapticFeedback | Object | 햅틱 피드백(아래 참고) |
TelegramWidget 메서드
| 메서드 | 동작 |
|---|---|
request(data[, options]) | 1~64바이트를 봇에 보냅니다. { result }(봇의 응답 또는 null)의 Promise를 반환하거나 WidgetRequestError로 reject됩니다. 탭 핸들러 안에서만, 또는 허용된 곳에서는 백그라운드로 호출할 수 있습니다. options에는 { wallet: true }를 넣을 수 있습니다 |
watchPublicData() / unwatchPublicData() | 화면에 있는 동안 공유 위젯의 공유 상태를 주기적으로 가져오기 시작 / 중지. 정적 위젯이나 미리보기에서는 효과 없음 |
copyText(text) | 탭할 때 1~256자를 복사하고, 앱이 복사한 텍스트를 토스트로 보여 줍니다 |
openLink(url) | 사용자 확인 후 https: URL(256자 이하, t.me 호스트 제외)을 엽니다 |
openTelegramLink(url) | 메시지 속 링크를 탭한 것처럼 https://t.me/… 링크를 텔레그램 안에서 엽니다 |
setResizeAnchor(edge) | top(기본) 또는 bottom: 높이가 바뀔 때 고정할 말풍선 가장자리 |
ready() | 선택 사항: 첫 상태를 다 그렸다고 앱에 알립니다 |
onEvent(type, handler) / offEvent(type, handler) | 이벤트 핸들러 추가 / 제거(이벤트 종류당 최대 16개) |
isProfileAtLeast(n) | profile >= n을 반환 |
isProfileAtLeast, request, 지갑 메서드를 제외한 모든 메서드는 동기식입니다. HapticFeedback에는 impactOccurred(style)(light, medium, heavy, rigid, soft), notificationOccurred(type)(error, success, warning), selectionChanged()가 있습니다. sendMessage는 없으며, 위젯은 자신의 widget_id도 알 수 없습니다.
이벤트
| 이벤트 | 발생 시점 |
|---|---|
themeChanged | 채팅 테마가 바뀜. colorScheme, themeParams, CSS 변수는 이미 갱신된 상태 |
activated / deactivated | 위젯이 보이게 됨 / 숨겨짐 (visibilitychange 이후) |
chatDataChanged | 봇이 채팅 상태를 바꿈. chatData는 이미 새 값. 전달본에서는 발생하지 않음 |
publicDataChanged | 봇이 공유 상태를 바꿈. 화면의 공유 위젯은 watch 중일 때만. 둘 다 바뀌면 chatDataChanged 다음에 발생 |
contentSafeAreaChanged | 메시지 시각이 가리는 영역이 바뀜(캡션 추가·삭제·이동, "수정됨" 표시) |
핸들러는 this가 TelegramWidget에 바인딩된 채 인자 없이 호출되므로 새 값은 객체에서 직접 읽습니다.
WidgetRequestError 오류 코드
button.addEventListener('click', () => {
status.textContent = '전송 중…';
TelegramWidget.request('vote:2').then(
(answer) => { status.textContent = answer.result ?? '완료'; },
(error) => { status.textContent = '오류: ' + error.code; }, // error.name === 'WidgetRequestError'
);
});
| code | 의미 |
|---|---|
NOT_ALLOWED | allow_queries 없음, 정적 위젯의 전달본, 백그라운드 요청이 꺼진 곳에서 탭 없이 호출, 미리보기, 요청을 전달하지 않는 앱 |
BUSY | 이 위젯의 다른 요청이나 지갑 호출이 진행 중 |
RATE_LIMITED | 직전 호출 후 5초 안의 백그라운드 호출, 또는 사용자·봇 쌍마다 5초에 5회 초과 |
TIMEOUT | 봇이 15초 안에 응답하지 않음(봇 중지, 느린 처리, widget_query·shared_widget_query 미수신) |
FAILED | 그 밖의 경우: 봇 차단·삭제, 메시지 삭제, 네트워크 실패 |
INVALID_ANSWER | 봇의 응답이 제한을 어김 |
REJECTED, BAD_REQUEST | 지갑 호출 전용: 사용자가 거절했거나 지갑이 트랜잭션·payload를 거부함 |
데이터가 비어 있거나 64바이트를 넘으면 전송 전에 TypeError가 발생합니다.
봇 쪽: widget_query와 answerWidgetQuery
원본 메시지에서 온 요청은 Update의 widget_query로, 전달된 공유 위젯에서 온 요청은 shared_widget_query로 도착합니다. getUpdates나 setWebhook(텔레그램 봇 웹훅 설정)에 allowed_updates를 지정한다면 두 종류를 모두 넣어야 합니다.
{
"update_id": 100000001,
"widget_query": {
"id": "8123456789012345678",
"from": {"id": 123456789, "is_bot": false, "first_name": "Alice"},
"chat": {"id": 123456789, "type": "private", "first_name": "Alice"},
"message_id": 4242,
"chat_instance": "901234567890123456",
"type": {"type": "data"},
"data": "refresh"
}
}
봇을 통해 보낸(인라인) 메시지에서 온 widget_query에는 chat·message_id 대신 inline_message_id와 chat_type이 있고, 공유 위젯이면 widget_id가 붙습니다. shared_widget_query에는 id, from, type, data, widget_id만 있습니다. 모든 요청에 answerWidgetQuery(widget_query_id, 선택적으로 최대 1024바이트의 data)로 응답하고, 상태는 별도로 editMessageWidgetData나 editSharedWidgetData로 바꿉니다. from과 widget_id는 텔레그램이 채우므로 위조할 수 없지만, data는 신뢰할 수 없는 입력으로 다루십시오.
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/answerWidgetQuery" \
-H "Content-Type: application/json" \
-d '{"widget_query_id": "8123456789012345678", "data": "{\"n\":5,\"r\":3}"}'
CSS 변수
| 변수 | 의미 |
|---|---|
--tg-theme-bg-color, --tg-theme-text-color, --tg-theme-hint-color, --tg-theme-link-color | 말풍선 배경, 본문, 보조 텍스트, 링크 |
--tg-theme-button-color, --tg-theme-button-text-color | 앱의 기본 버튼 |
--tg-theme-secondary-bg-color, --tg-theme-accent-text-color, --tg-theme-subtitle-text-color, --tg-theme-destructive-text-color, --tg-theme-section-separator-color | 보조 배경, 강조, 부제목, 위험 동작, 구분선 |
--tg-color-scheme | light 또는 dark |
--tg-text-font-size, --tg-text-line-height, --tg-text-padding | 메시지 글자 크기(약 15px), 줄 높이(약 1.35), 말풍선 텍스트 여백(약 8px 12px) |
--tg-button-bg, --tg-button-text, --tg-button-radius, --tg-button-font, --tg-button-padding, --tg-button-height, --tg-button-pressed-opacity, --tg-button-disabled-opacity | 기본 <button>에 쓰이는 앱 버튼 스타일 |
--tg-content-safe-area-inset-*, --tg-content-safe-area-corner-left / -right | 메시지 시각이 그려지는 띠 영역(env(safe-area-inset-*)와 같음) |
앱은 이 변수들을 루트 요소에 !important로 지정하므로, 내 요소에서만 재정의할 수 있습니다. prefers-color-scheme, light-dark(), color-scheme는 시스템이 아니라 채팅 테마를 따릅니다.
제스처와 touch-action
탭과 더블 탭은 항상 위젯이 받고, 세로 드래그는 항상 채팅 스크롤이 가져갑니다(위젯은 pointercancel을 받음). 길게 누르기와 가로 드래그는 요소별로 CSS touch-action으로 가져옵니다. auto는 채팅에 맡기고(메시지 메뉴, 스와이프해서 답장), pan-y는 가로 드래그를 위젯에 주며, none은 길게 누르기(contextmenu)와 가로 드래그를 모두 위젯에 줍니다. 기준은 간단합니다. 누르고 있는 버튼, 게임 컨트롤, 캔버스에는 touch-action: none, 가로 슬라이더나 캐러셀에는 pan-y, 나머지는 auto입니다. 터치 이벤트는 전달되지 않으므로 포인터 이벤트를 쓰십시오. 위젯의 시작 쪽 가장자리 20px는 어떤 요소도 가져갈 수 없으므로 컨트롤을 두지 마십시오.
위젯 프로필에서 제거되는 기능
- 폼 컨트롤(
input,select,textarea). 컨트롤은<button>뿐이며 키보드 이벤트와 포커스도 없습니다. - 모든 네트워크 API(
fetch,XMLHttpRequest,WebSocket등은NetworkDisabledError를 던짐), 외부 스크립트·스타일·폰트·이미지,location,history. vh등 높이 기준 단위,overflow: auto / scroll(hidden으로 바뀜),position: sticky,@font-face,:has(), CSS 중첩.alert,confirm,prompt,navigator.clipboard(copyText를 사용),iframe,video,audio, WebGL.
제거된 기능 때문에 위젯이 깨지지는 않습니다. 해당 요소, 선언, 이벤트만 빠지고 나머지는 계속 동작합니다. CSS.supports()와 @supports는 프로필에 맞춰 응답합니다.
텔레그램 위젯 제한값
| 항목 | 값 | 초과 시 |
|---|---|---|
| HTML | 32768바이트, zlib 레벨 9 압축 후 4096바이트 | INPUT_MEDIA_WIDGET_TOO_LARGE |
chat_data, public_data | 각각 UTF-8 1024바이트 | INPUT_MEDIA_WIDGET_DATA_TOO_LARGE |
| 요청 데이터 | 1~64바이트 | 위젯에서 TypeError |
| 응답 데이터 | 1024바이트 | WIDGET_RESULT_TOO_LARGE |
| 응답 시간 | 15초 | TIMEOUT, 늦은 응답은 query is too old |
| 요청 횟수 | 사용자·봇 쌍마다 5초에 5회 | RATE_LIMITED |
| 공유 위젯 수정 | 초당 1회. 갱신 주기 기본 30초, cache_time 5~3600 | flood wait, 5 미만이면 invalid cache time specified |
| CPU | 초당 JavaScript 300ms, 한 작업당 500ms | 속도 제한, 위젯 중지 |
| 메모리 | 8MB | 위젯 중지 |
| DOM 노드 | 2000개 | 위젯 중지 |
| 타이머 | 동시에 살아 있는 타이머 64개 | RangeError |
localStorage, sessionStorage | 메시지당 영역별 4KB | QuotaExceededError |
| 말풍선 | 너비 200px~말풍선 최대 너비, 높이 50~600px | 잘림 |
중지된 위젯은 마지막 프레임에 "Widget stopped" 배지를 달고 남아 있다가 다시 화면에 나타날 때 새로 만들어집니다. 연속으로 두 번 중단되면 앱을 재시작할 때까지 중지된 상태로 남습니다.
스토리지, 링크, 햅틱, copyText
- Web Storage는 이 기기의 이 메시지에 속합니다. 앱을 재시작해도 남지만 봇에 전송되지 않고 기기 간에 동기화되지도 않습니다.
setItem은try/catch로 감싸십시오. - 링크:
openLink,openTelegramLink,copyText,request는 실제 탭이 필요합니다.await나 타이머 뒤가 아니라click핸들러 안에서 동기적으로 호출하십시오. 탭 한 번에 이런 호출 한 번이 허용됩니다. 잘못된 URL은TypeError를 던지며, 탭한<a href="https://…">도 동작합니다. - 햅틱은 위젯이 보일 때만, 한 번에 최대 5회, 초당 10회까지 재생됩니다. 터치 중과 손을 뗀 뒤 5초 동안은 제약 없이 쓸 수 있습니다. 데스크톱과 웹 앱에서는 재생되지 않습니다.
- copyText는 1~256자를 복사하고 복사한 텍스트를 항상 토스트로 보여 줍니다.
TON 지갑 결제 간단 정리
위젯은 TON Connect 형식을 사용해 텔레그램 내장 지갑으로 결제를 요청할 수 있습니다. 결제 버튼은 TelegramWidget.wallet이 null이 아닐 때만 그리십시오. 탭하면 위젯이 request(data, { wallet: true })를 보내고, 봇이 받는 요청의 type은 {"type": "data", "wallet_card": …}가 됩니다. 봇은 새 트랜잭션으로 응답하고, 위젯은 응답 핸들러에서 wallet.sendTransaction()을 호출합니다. 이 호출은 10초 안이라면 두 번째 탭이 필요 없습니다.
TelegramWidget.request('pay:42', { wallet: true })
.then((a) => TelegramWidget.wallet.sendTransaction(JSON.parse(a.result), 'paid:42'))
.then((a) => show(a.result), (e) => showError(e.code));
이후 봇은 메시지 해시가 담긴 sent_transaction 타입의 요청을 받으며, 트랜잭션을 체인에서 직접 검증해야 합니다. TIMEOUT이 났더라도 결제가 완료되었을 수 있으므로, 다시 결제하게 하지 말고 봇에 주문 상태를 확인하십시오.
위젯 관련 Bot API 오류
| 오류 | 원인 |
|---|---|
INPUT_MEDIA_WIDGET_TOO_LARGE | HTML이 32768바이트 또는 압축 후 4096바이트 초과 |
INPUT_MEDIA_WIDGET_HTML_INVALID | html에 잘못된 UTF-8 또는 NUL 문자가 있음 |
INPUT_MEDIA_WIDGET_DATA_TOO_LARGE | chat_data나 public_data가 1024바이트 초과 |
INPUT_MEDIA_WIDGET_DATA_INVALID / WIDGET_DATA_INVALID | 전송 시 / 수정 시 상태 텍스트가 잘못됨 |
message is not modified | 아무것도 바꾸지 않는 수정. 성공으로 처리하십시오 |
내 토큰으로 Bot API Tester에서 메서드를 직접 호출해 보고, sendWidget의 파라미터도 확인해 보십시오. 아직 토큰이 없다면 텔레그램 봇 토큰 가이드를 참고하고, 10.4에 추가된 다른 메서드는 메서드 레퍼런스에서 볼 수 있습니다.
자주 묻는 질문
TelegramWidget을 쓰려면 스크립트를 따로 넣어야 하나요?
아닙니다. 텔레그램 안에서는 위젯의 첫 스크립트가 실행되기 전에 상태, 테마, 컨텍스트가 채워진 window.TelegramWidget이 이미 존재합니다. 텔레그램 밖에서는 undefined이므로 브라우저에서 열 때는 존재 여부를 확인하십시오.
WidgetRequestError NOT_ALLOWED는 무슨 뜻인가요?
이 메시지에서는 요청을 보낼 수 없다는 뜻입니다. 위젯이 allow_queries 없이 전송되었거나, 정적 위젯의 전달본 또는 미리보기이거나, 백그라운드 요청이 허용되지 않는 곳에서 탭 없이 request()를 호출한 경우입니다.
봇은 widget_query에 얼마나 빨리 응답해야 하나요?
15초 안에 answerWidgetQuery로 응답해야 합니다. 시간이 지나면 위젯의 Promise는 TIMEOUT으로 reject되고, 늦은 응답은 query is too old로 거부됩니다. 처리에 실패했더라도 모든 요청에 응답하십시오.
위젯이 chatData나 publicData를 직접 바꿀 수 있나요?
없습니다. 두 값은 위젯에서 읽기 전용입니다. 상태는 봇만 sendWidget, editMessageWidgetData, editSharedWidgetData로 쓸 수 있고, 위젯은 TelegramWidget.request()로 봇에 요청할 수만 있습니다.
TelegramWidget.sendMessage 메서드가 있나요?
없습니다. 위젯에는 sendMessage가 없으며, 사용자 대신 채팅에 무언가를 보내는 일은 일어나지 않습니다. 위젯이 할 수 있는 것은 봇에 요청 보내기, 텍스트 복사, 링크 열기, 햅틱 재생뿐입니다.
관련 가이드
텔레그램 봇 만들기: @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 검증 코드, 게시물 임베드, 댓글, 공유 버튼까지 다룹니다.
텔레그램 위젯 예제: HTML과 Python 봇 코드 전체 공개
바로 실행할 수 있는 텔레그램 위젯 예제 모음입니다. 정적 주문 카드, widget_query 카운터, 실시간 공유 투표, 브라우저 미리보기까지 HTML과 Python 코드로 설명합니다.
텔레그램 위젯 가이드: 봇 메시지 안에서 동작하는 HTML 위젯
Bot API 10.4에 추가된 텔레그램 위젯의 개념, sendWidget 사용법, chat_data와 public_data, 현재 사용 가능한 범위와 Mini App과의 차이를 정리했습니다.