Telegram Bot API

텔레그램 미니앱 테스트 가이드: 브라우저 목 모드부터 실제 텔레그램까지

· 8 분 분량

텔레그램 미니앱 테스트는 일반 브라우저에서 Telegram.WebApp을 목(mock)으로 대체해 UI를 만드는 것부터 시작합니다. 그다음 로컬 빌드를 HTTPS로 노출해 @BotFather에 URL을 등록하고, 텔레그램 안에서 DevTools를 연결해 확인합니다. 마지막 단계는 서버에서 이루어집니다. 사용자를 신뢰하기 전에 initData를 검증해야 합니다. 아래에서 localhost 개발부터 운영 체크리스트까지 전체 흐름을 설명합니다.

1단계: 일반 브라우저에서 UI 테스트하기

텔레그램 밖에서는 Telegram.WebApp 뒤에 클라이언트가 없습니다. 실행 데이터도, 테마도, 네이티브 버튼도 없습니다. 그래도 코드가 이런 상황을 견딜 수 있게 작성하면 인터페이스 대부분은 데스크톱 브라우저에서 만들 수 있습니다.

const tg = window.Telegram?.WebApp;
const insideTelegram = Boolean(tg?.initData);

if (insideTelegram) {
  tg.ready();   // 로딩 화면을 최대한 빨리 숨깁니다
  tg.expand();
} else {
  console.info("텔레그램 밖에서 실행 중: 목 데이터를 사용합니다");
}

스타일에는 var(--tg-theme-bg-color, #fff)처럼 테마 변수와 기본값을 함께 지정해 두면 두 환경 모두에서 읽기 좋은 화면이 유지됩니다.

코드를 작성하지 않고 각 API 호출이 어떻게 동작하는지 보고 싶다면 Mini App Tester를 여십시오. 일반 브라우저에서는 목 모드로 실행되어 Telegram.WebApp을 흉내 냅니다. MainButton과 BackButton을 누르고, 팝업을 열고, CloudStorage에 쓰고, 테마를 바꾸면서 45개 이상의 이벤트를 로그로 확인할 수 있습니다. 다만 목 데이터는 어디까지나 대역입니다. 이 initData는 텔레그램이 서명한 것이 아니므로 서버 측 검증에서 (당연히) 실패합니다.

2단계: localhost의 텔레그램 미니앱을 HTTPS로 열기

텔레그램은 HTTPS 주소의 미니앱만 엽니다(테스트 환경은 예외). 게다가 휴대폰에서는 http://localhost에 접속할 수도 없습니다. 그래서 localhost에서 텔레그램 미니앱을 테스트할 때는 개발 서버에 공개 HTTPS 주소를 붙여 주는 터널을 쓰는 것이 표준적인 방법입니다.

# 개발 서버를 실행합니다(예: 5173 포트의 Vite)
npm run dev

# 다른 터미널에서 터널 중 하나를 사용합니다
ngrok http 5173
cloudflared tunnel --url http://localhost:5173

어느 도구든 공개 https:// URL을 출력합니다. 자주 걸리는 문제는 두 가지입니다.

3단계: @BotFather에 미니앱 등록하기

미니앱은 항상 봇에 속합니다. 아직 봇이 없다면 텔레그램 봇 만들기를 먼저 진행하십시오. 그다음 사용자가 URL을 여는 방식을 고릅니다.

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setChatMenuButton" \
  -H "Content-Type: application/json" \
  -d '{"menu_button": {"type": "web_app", "text": "앱 열기",
       "web_app": {"url": "https://your-tunnel.example.com"}}}'

chat_id 없이 호출하면 모든 사용자의 기본 메뉴 버튼이 설정됩니다. 터널 URL이 바뀔 때마다 curl을 다시 입력하는 대신 Bot API Tester의 setChatMenuButton에서 다시 호출하면 편합니다.

4단계: 텔레그램 테스트 환경 사용하기

텔레그램은 별도의 테스트 환경을 운영합니다. 이곳에서는 미니앱 링크에 TLS 없는 일반 HTTP를 쓸 수 있어 로컬 네트워크에서 테스트할 때 유용합니다. 전용 계정과 전용 봇이 필요합니다.

테스트 계정에서 @BotFather로 봇을 만들고 API 호출은 https://api.telegram.org/bot<token>/test/METHOD_NAME으로 보냅니다. 이곳의 플러드 제한은 완화되지 않으며 오히려 더 엄격할 수 있으므로 부하 테스트용은 아닙니다. Bot API Tester의 TEST 스위치를 포함한 전체 설정 방법은 텔레그램 테스트 서버 사용법에서 다룹니다.

5단계: 텔레그램 안에서 미니앱 디버깅하기

Chrome에서는 전혀 나타나지 않던 버그가 실제 WebView에서만 드러나는 경우가 많습니다. 텔레그램 공식 Debug Mode for Mini Apps 안내를 요약하면 다음과 같습니다.

플랫폼검사 방법
iOS설정 아이콘을 10번 탭하고 Allow Web View Inspection을 켭니다. USB로 연결한 뒤 Mac의 Safari에서 Develop → 내 기기를 엽니다.
AndroidUSB 디버깅을 켭니다. 텔레그램 설정 맨 아래에서 버전 번호를 두 번 길게 누르고 Enable WebView Debug를 선택한 뒤 Chrome에서 chrome://inspect/#devices를 엽니다.
Telegram Desktop (Windows, Linux)베타 버전을 설치하고 Settings → Advanced → Experimental settings → Enable webview inspection을 켠 뒤 우클릭 → Inspect를 선택합니다.
Telegram for macOS베타 버전을 설치하고 설정 아이콘을 5번 클릭해 Debug Mini Apps를 켠 뒤 우클릭 → Inspect Element를 선택합니다.

여러 클라이언트를 빠르게 비교하려면 테스트용 봇의 미니앱 URL로 https://telegram-bot-api.info/telegram-mini-app-tester.html을 지정하십시오. 텔레그램 안에서 Mini App Tester는 실제 API를 사용하며 version, platform, colorScheme, themeParams, 세이프 에어리어, 그리고 해당 클라이언트가 발생시키는 모든 이벤트를 보여 줍니다. 직접 작성하는 코드에서는 모든 사용자가 최신 앱을 쓴다고 가정하지 말고 Telegram.WebApp.isVersionAtLeast("8.0")으로 새 기능을 분기하십시오.

6단계: 서버에서 initData 검증하기

Telegram.WebApp.initDataUnsafe는 화면 표시용으로만 쓰십시오. 원본 Telegram.WebApp.initData 문자열을 백엔드로 보내 다음 순서로 검증합니다.

  1. 쿼리 문자열을 파싱하고 hash를 제거합니다.
  2. 나머지 필드를 알파벳순으로 정렬해 key=value 형태로 \n으로 이어 붙입니다. 이것이 data_check_string입니다.
  3. secret_key = HMAC_SHA256(key="WebAppData", message=bot_token)을 계산합니다.
  4. hex(HMAC_SHA256(key=secret_key, message=data_check_string))이 hash와 같으면 진짜 데이터입니다.
  5. auth_date를 확인해 오래된 데이터는 거부합니다.
import crypto from "node:crypto";

export function validateInitData(initData, botToken, maxAgeSec = 3600) {
  const params = new URLSearchParams(initData);
  const hash = params.get("hash") ?? "";
  params.delete("hash");

  const dataCheckString = [...params.keys()].sort()
    .map((key) => `${key}=${params.get(key)}`)
    .join("\n");

  const secretKey = crypto.createHmac("sha256", "WebAppData").update(botToken).digest();
  const expected = crypto.createHmac("sha256", secretKey).update(dataCheckString).digest("hex");

  const valid = hash.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(expected));
  const age = Date.now() / 1000 - Number(params.get("auth_date"));
  if (!valid || !(age <= maxAgeSec)) return null;

  return { ...Object.fromEntries(params), user: JSON.parse(params.get("user") ?? "null") };
}

클라이언트에서는 fetch("/api/session", { method: "POST", body: Telegram.WebApp.initData })처럼 문자열을 그대로 보내고, 앱을 실행한 봇의 토큰으로 검증합니다. 토큰을 알려 줄 수 없는 제3자는 공식 문서에 설명된 대로 텔레그램의 Ed25519 공개 키로 signature 필드를 검증할 수 있습니다.

Bot API 10.2: 미니앱 출처(origin) 보호

Bot API 10.2에서는 원래 미니앱 도메인이 아닌 출처에서 미니앱 메서드를 호출하는 것이 금지되었고, 이 보호는 2026년 7월 20일 모든 미니앱에 적용되었습니다. 테스트 중에는 앱이 등록된 터널 URL에서 스테이징 도메인이나 로그인 페이지 같은 다른 호스트로 리디렉션할 때 문제가 됩니다. 그곳에서는 Telegram.WebApp 호출이 동작하지 않습니다. 텔레그램과 통신하는 코드는 등록된 도메인에 두고, 터널 호스트가 바뀔 때마다 URL을 다시 등록하십시오. @BotFather의 미니앱 설정에서 보호를 해제할 수도 있지만, 그 경우 미니앱에 신뢰할 수 없는 사이트로 향하는 링크가 없도록 보장하는 책임은 개발자에게 있습니다.

텔레그램 미니앱 테스트 체크리스트

검증 코드는 봇 토큰에 의존하므로 토큰을 안전하게 보관해야 합니다. 텔레그램 봇 토큰 발급과 관리를 참고하십시오. 같은 백엔드에서 봇 업데이트도 받는다면 텔레그램 봇 웹훅 설정으로 이어서 진행하면 됩니다. 완전한 웹 앱이 아니라 채팅 메시지 안의 작은 인터랙티브 블록만 필요하다면 Bot API 10.4에서 추가된 텔레그램 위젯을 살펴보십시오.

자주 묻는 질문

텔레그램 미니앱을 localhost에서 테스트하려면 어떻게 하나요?

텔레그램은 HTTPS 주소의 미니앱만 열기 때문에 ngrok이나 Cloudflare Tunnel 같은 HTTPS 터널로 개발 서버를 노출하고, 그 URL을 @BotFather나 setChatMenuButton으로 등록합니다. 테스트 환경에서는 일반 HTTP 링크도 허용됩니다.

텔레그램 없이 미니앱을 테스트할 수 있나요?

일부만 가능합니다. 일반 브라우저에는 텔레그램 클라이언트가 없으므로 Mini App Tester의 목 모드처럼 Telegram.WebApp을 흉내 내는 환경이 필요합니다. 실제 initData, 네이티브 팝업, 햅틱은 텔레그램 안에서만 동작합니다.

텔레그램 미니앱에서 DevTools는 어떻게 여나요?

iOS는 설정 아이콘을 10번 눌러 Allow Web View Inspection을 켜고 Mac의 Safari 개발자 메뉴를 사용합니다. Android는 텔레그램 디버그 설정에서 WebView Debug를 켜고 chrome://inspect/#devices를 엽니다. 데스크톱과 macOS는 베타 앱의 웹뷰 검사 옵션을 사용합니다.

initData 검증이 계속 실패하는 이유는 무엇인가요?

원본 initData 문자열 대신 initDataUnsafe를 검증하는 경우, 다른 봇의 토큰을 쓰는 경우, 값을 URL 디코딩하지 않은 경우, data-check-string에 hash를 남겨 둔 경우, HMAC의 키와 메시지를 뒤바꾼 경우, 텔레그램이 서명하지 않은 목 데이터로 테스트하는 경우가 대표적입니다.

다른 도메인에서 Telegram.WebApp 메서드가 동작하지 않는 이유는 무엇인가요?

Bot API 10.2부터 미니앱 도메인과 다른 출처(origin)에서 미니앱 메서드를 호출하면 차단되며, 2026년 7월 20일부터 모든 미니앱에 적용되었습니다. 앱을 등록된 도메인에서 실행하거나 @BotFather에서 이 보호를 해제하십시오.

텔레그램 미니앱용 테스트 서버가 따로 있나요?

있습니다. 테스트 환경은 운영 환경과 완전히 분리되어 있어 새 계정과 새 봇이 필요하고, Bot API 호출은 https://api.telegram.org/bot<token>/test/METHOD_NAME으로 보내며, 미니앱 링크에 TLS 없는 HTTP를 쓸 수 있습니다.

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

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

텔레그램 봇 배포와 호스팅: VPS, Docker, 서버리스

텔레그램 봇 배포 방법: 폴링과 웹훅 선택, VPS의 systemd 서비스, Docker, secret_token을 검증하는 Cloudflare Workers, 출시 전 체크리스트까지 정리했습니다.

텔레그램 봇 API 10.0~10.5 변경 사항: 봇 설정, 위젯, 리치 메시지, 임시 메시지, 게스트 모드

텔레그램 봇 API 10.0~10.5의 새 기능을 정리했습니다. setMySettings와 BotFullInfo, HTML 위젯, 리치·임시 메시지, 게스트 모드를 JSON 예제와 함께 설명합니다.

텔레그램 봇 API 오류 총정리: 오류별 의미와 해결 방법

텔레그램 봇 API 오류를 코드별로 정리했습니다. 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 retry_after의 원인과 해결, 처리 코드까지 다룹니다.

텔레그램 봇 API 제한 총정리: 전송 속도, 429 오류, 파일 크기, 메시지 길이

텔레그램 봇 API 전송 제한을 정리했습니다. 초당 30건, 채팅당 초당 1건, 그룹 분당 20건 기준과 429 retry_after 처리, 파일 크기·메시지 길이 제한까지 다룹니다.

텔레그램 봇 명령어 가이드: setMyCommands, 명령어 스코프, /start 딥링크

텔레그램 봇 명령어 설정 방법: @BotFather /setcommands, 스코프·언어별 setMyCommands, /start 딥링크 파라미터, 그룹의 /cmd@bot 처리를 예제로 설명합니다.

텔레그램 봇 키보드: 인라인 키보드, 콜백 버튼, 리플라이 키보드

텔레그램 봇 버튼 만드는 법을 정리했습니다. callback_data 인라인 키보드, answerCallbackQuery, 버튼을 누른 뒤 메시지 수정, 리플라이 키보드와 ForceReply까지 다룹니다.

n8n 텔레그램 연동 가이드: 봇 연결, 워크플로 트리거, 메시지 보내기

n8n 텔레그램 연동 방법: 봇 토큰을 Access Token으로 등록하고, 공개 HTTPS로 Telegram Trigger 웹훅을 받고, chat id로 메시지를 보내며 자주 나는 오류를 해결합니다.

텔레그램 봇 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의 의미, 결과가 비어 있을 때 해결법까지 설명합니다.

텔레그램 인라인 봇 가이드: 인라인 모드 활성화와 인라인 쿼리 응답

텔레그램 인라인 봇 만드는 법: @BotFather나 setMySettings로 인라인 모드를 켜고 inline_query에 answerInlineQuery로 답하는 과정을 Python·JS 예제로 설명합니다.

텔레그램 스타 결제 봇 가이드: 인보이스, 결제 전 확인, 환불, 구독

텔레그램 봇에서 스타(Stars) 결제 받는 법: XTR sendInvoice, pre_checkout_query, successful_payment, 환불, 구독까지 Python·JS 코드로 설명합니다.

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

텔레그램 테스트 서버 사용법을 정리했습니다. 테스트 환경 로그인, 테스트용 봇 만들기, /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 코드로 설명합니다.

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

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