Telegram Bot API

텔레그램 Mini App initData 검증 도구

Telegram.WebApp.initData와 봇 토큰을 붙여넣어 Mini App hash가 유효한지 확인하십시오. 서버에서 실행해야 하는 것과 같은 HMAC-SHA256 검사를 브라우저에서 로컬로 수행합니다.

토큰은 브라우저(localStorage)에만 저장되며 api.telegram.org로만 전송됩니다.

알고리즘: secret_key = HMAC_SHA256("WebAppData", bot_token); hash = hex(HMAC_SHA256(secret_key, data_check_string)). 여기서 data_check_string은 hash를 제외한 모든 필드를 키 순으로 정렬해 key=value 형태로 \n으로 이은 문자열입니다.

텔레그램 Mini App hash 확인 방법

  1. Mini App에서 원본 initData 문자열을 구하십시오. 예를 들어 Telegram.WebApp.initData(initDataUnsafe가 아님)를 로그로 출력합니다. tgWebAppData=로 시작하는 URL 프래그먼트도 됩니다. 접두사는 자동으로 제거됩니다.
  2. Mini App을 여는 봇의 토큰을 붙여넣으십시오.
  3. 검증을 누르십시오. 유효/무효 판정, 경과 시간이 포함된 auth_date(24시간보다 오래되면 경고), 그리고 user 등 JSON 값이 디코딩된 모든 필드가 표시됩니다.

검증 방식

도구는 Validating data received via the Mini App의 공식 알고리즘을 따릅니다.

  1. initData를 쿼리 문자열로 파싱하고 hash를 따로 빼 둡니다.
  2. data_check_string을 만듭니다: 나머지 모든 필드를 key=value(URL 디코딩된 값) 형태로 알파벳순 정렬해 줄바꿈 \n으로 잇습니다.
  3. secret_key = HMAC_SHA256(key="WebAppData", message=bot_token).
  4. hex(HMAC_SHA256(key=secret_key, message=data_check_string))가 hash와 같으면 데이터가 유효합니다.

Node.js 서버에서 같은 검사를 하는 코드:

const crypto = require('crypto');

function checkInitData(initData, botToken) {
  const params = new URLSearchParams(initData);
  const hash = params.get('hash');
  params.delete('hash');
  const dataCheckString = [...params]
    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
    .map(([k, v]) => `${k}=${v}`)
    .join('\n');
  const secret = crypto.createHmac('sha256', 'WebAppData').update(botToken).digest();
  const calc = crypto.createHmac('sha256', secret).update(dataCheckString).digest('hex');
  return calc === hash;
}

가로챈 오래된 initData가 재사용되지 않도록 서버에서 auth_date도 확인하십시오.

hash가 일치하지 않는 이유

개인정보 보호

브라우저 밖으로 나가는 요청은 없습니다. HMAC은 Web Crypto API로 계산되고, 토큰은 localStorage에만 저장되며 저희 서버에는 아무것도 전달되지 않습니다. 실제 실행에서 나온 initData를 보려면 텔레그램 안에서 /ko/telegram-mini-app-tester.html를 여십시오. 전체 테스트 과정은 /ko/guides/test-telegram-mini-app.html에 있으며, 새 토큰이 필요하면 /ko/guides/telegram-bot-token.html을 참고하십시오.

자주 묻는 질문

텔레그램 Web App init data는 어떻게 검증하나요?

secret_key = HMAC_SHA256("WebAppData", bot_token)를 계산하고, hash를 제외한 모든 필드를 키 순으로 정렬해 \n으로 이어 data-check-string을 만든 다음, hex(HMAC_SHA256(secret_key, data_check_string))를 hash와 비교합니다. 위 도구가 정확히 이 작업을 합니다.

initData hash가 무효로 나오는 이유는 무엇인가요?

대개 토큰이 다른 봇의 것이거나 initData가 변경되었기 때문입니다. 디코딩, 재인코딩, 잘림, 또는 initDataUnsafe로 다시 만든 경우입니다. 원본 Telegram.WebApp.initData 문자열을 붙여넣으십시오.

initDataUnsafe를 신뢰해도 되나요?

서버에서는 안 됩니다. initDataUnsafe는 클라이언트에서 파싱된 데이터일 뿐입니다. 원본 initData를 백엔드로 보내 그곳에서 hash를 검증한 뒤에 사용자 ID를 신뢰하십시오.

initData는 얼마나 오래된 것까지 허용되나요?

텔레그램은 오래된 데이터를 거부하도록 auth_date를 확인할 것을 권장하지만, 기준은 직접 정하면 됩니다. 도구는 경과 시간을 보여 주고 데이터가 24시간보다 오래되면 경고합니다.

봇 토큰이 어딘가로 전송되나요?

아닙니다. 검증 도구는 네트워크 요청을 보내지 않으며, hash는 브라우저의 Web Crypto API로 계산합니다. 토큰은 localStorage에 기억될 뿐입니다.

다른 유틸리티

chat ID 찾기MarkdownV2·HTML 이스케이프 도구웹훅 확인 도구Bot API Tester