텔레그램 웹사이트 위젯: 로그인 위젯, 게시물 임베드, 댓글, 공유 버튼
텔레그램이 웹사이트용으로 제공하는 위젯은 네 가지입니다. 텔레그램 계정으로 가입·로그인하게 해 주는 Telegram Login(텔레그램 로그인 위젯), 공개 채널이나 그룹의 메시지를 넣는 게시물 위젯, 채널 게시물의 댓글을 보여 주는 디스커션 위젯, 그리고 공유 버튼입니다. 모두 내 HTML에 붙여 넣는 짧은 코드 조각입니다. Bot API 10.4부터 봇이 채팅 메시지 안에 보내는 인터랙티브 위젯과는 다른 기능이며, 그쪽은 봇 메시지 속 텔레그램 위젯에서 다룹니다.
텔레그램 웹사이트 위젯 한눈에 보기
| 위젯 | 하는 일 | 봇 필요 여부 | 코드 얻는 방법 |
|---|---|---|---|
| Telegram Login | 텔레그램 계정으로 가입·로그인 (OpenID Connect) | 필요. @BotFather에서 Allowed URLs와 Client ID 설정 | core.telegram.org/bots/telegram-login의 설정 도구 |
| Login Widget (레거시) | 예전 iframe 방식 로그인 버튼, 현재 보관 상태 | 필요. /setdomain으로 도메인 연결 | core.telegram.org/widgets/login-legacy |
| 게시물 위젯 | 공개 채널·그룹의 메시지 임베드 | 불필요 | t.me 링크 → EMBED, 또는 게시물 설정 도구 |
| 디스커션 위젯 | 채널 게시물과 댓글 표시 | 불필요 | 디스커션 설정 도구 |
| 공유 버튼 | 방문자가 내 링크를 채팅, 그룹, 채널, 저장한 메시지로 보냄 | 불필요 | 공유 버튼 생성기 또는 일반 링크 |
Telegram Login: 새로운 텔레그램 로그인 (OpenID Connect)
현재의 Telegram Login은 JavaScript 라이브러리이면서, PKCE를 쓰는 Authorization Code Flow 기반의 표준 OpenID Connect 제공자입니다. 라이브러리의 버튼을 그대로 써도 되고, OIDC를 지원하는 라이브러리나 인증 플랫폼(텔레그램은 Keycloak, Authentik, Auth0를 예로 듭니다), iOS·Android용 네이티브 SDK를 써도 됩니다.
- 사이트를 대표할 봇을 준비합니다(텔레그램 봇 만들기). 사용자는 확인 창에서 봇의 이름과 프로필 사진을 보게 되므로 사이트 이름, 로고와 맞춰 두십시오.
- Allowed URLs를 등록합니다. @BotFather Mini App을 열고 봇을 선택한 뒤 Login Widget으로 들어갑니다. 버튼을 넣을 origin(예:
https://example.com)과 OIDC 리디렉션 URI(예:https://example.com/auth/callback)를 추가합니다. 텔레그램은 미리 등록된 URL에 대해서만 로그인을 처리하고 리디렉션합니다. - 같은 화면에 표시되는 Client ID와 Client Secret을 저장합니다. Secret은 서버에만 두십시오.
- 페이지에 버튼을 추가합니다.
- 사용자 데이터를 믿기 전에 서버에서 ID 토큰을 검증합니다.
공식 설정 도구가 만들어 주는 코드는 다음과 같은 형태입니다. data-request-access는 선택 사항으로, write는 봇이 사용자에게 메시지를 보낼 수 있게 하고 phone은 인증된 전화번호를 요청합니다.
<script async src="https://oauth.telegram.org/js/telegram-login.js?6" data-client-id="123456789" data-onauth="onTelegramAuth(data)" data-request-access="write"></script>
<button class="tg-auth-button">텔레그램으로 로그인</button>
<script>
function onTelegramAuth(data) {
if (data.error) return console.warn(data.error);
// data.id_token을 서버로 보내 그곳에서 검증합니다
fetch('/auth/telegram', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({id_token: data.id_token})
});
}
</script>
콜백은 id_token(OIDC JWT), user(디코딩된 클레임) 또는 error를 받습니다. 라이브러리에는 JS API도 있습니다. Telegram.Login.init(InitOptions, callback), Telegram.Login.open([callback]), Telegram.Login.auth(InitOptions, callback)이고, 옵션은 client_id, scope, lang, nonce입니다. nonce는 서버에서 생성한 임의 문자열로, 재전송 공격을 막기 위해 id_token 안에 들어갑니다.
팝업과 COOP:telegram-login.js는 팝업 창과 통신합니다. 사이트가Cross-Origin-Opener-Policy: same-origin헤더를 보내면 로그인이 실패하므로, 헤더를 제거하거나same-origin-allow-popups로 바꾸십시오.
스코프와 OIDC 엔드포인트
| 스코프 | 얻는 정보 | 클레임 |
|---|---|---|
openid | 필수. 고유 식별자와 인증 시각 | sub, iss, iat, exp |
profile | 사용자 ID, 이름, username, 사진 URL | id, name, preferred_username, picture |
phone | 사용자가 동의한 경우 인증된 전화번호 | phone_number |
telegram:bot_access | 로그인 후 봇이 사용자에게 메시지를 보낼 수 있음 | — |
OIDC 클라이언트에는 디스커버리 문서 https://oauth.telegram.org/.well-known/openid-configuration, 응답 타입 code, S256 PKCE를 설정합니다. 흐름을 직접 구현한다면 엔드포인트는 https://oauth.telegram.org/auth, https://oauth.telegram.org/token(Basic 인증 base64(client_id:client_secret)을 쓰는 서버 측 POST), https://oauth.telegram.org/.well-known/jwks.json입니다. 텔레그램에는 별도의 UserInfo 엔드포인트가 없고 모든 데이터가 ID 토큰에 들어 있으므로, 라이브러리가 userinfo 요청을 보내려 한다면 건너뛰도록 설정하십시오.
ID 토큰 검증하기
JWKS 엔드포인트의 키로 JWT 서명을 검증한 뒤, iss가 https://oauth.telegram.org인지, aud가 내 봇 ID(client_id로 넘기는 값)와 같은지, exp가 지나지 않았는지 확인합니다. 토큰은 기본적으로 RS256으로 서명되며, @BotFather의 Login Widget > Advanced에서 ES256, EdDSA, ES256K를 고를 수 있습니다(EdDSA와 ES256K는 openid 스코프만 허용). jose 라이브러리를 쓴 Node.js 예제입니다.
import { createRemoteJWKSet, jwtVerify } from 'jose';
const JWKS = createRemoteJWKSet(new URL('https://oauth.telegram.org/.well-known/jwks.json'));
export async function verifyTelegramIdToken(idToken) {
const { payload } = await jwtVerify(idToken, JWKS, {
issuer: 'https://oauth.telegram.org',
audience: '123456789' // 내 Client ID (봇 ID)
});
return payload; // sub, id, name, preferred_username, picture, phone_number...
}
기존 텔레그램 로그인 위젯 (레거시)
아직 많은 사이트가 예전 iframe 방식의 Login Widget을 쓰고 있습니다. 문서가 보관 상태이므로 새 프로젝트에는 위의 방식을 쓰고, 기존 위젯을 유지보수해야 할 때 아래 내용을 참고하십시오.
- @BotFather에
/setdomain을 보내 웹사이트 도메인을 봇에 연결합니다. - 스크립트를 넣습니다. 콜백을 쓰는 예입니다.
<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-login="your_bot" data-size="large" data-onauth="onTelegramAuth(user)" data-request-access="write"></script>
<script type="text/javascript">
function onTelegramAuth(user) {
alert('로그인됨: ' + user.first_name + ' ' + user.last_name + ' (' + user.id + (user.username ? ', @' + user.username : '') + ')');
}
</script>
data-onauth 대신 data-auth-url="https://example.com/auth/telegram"을 지정할 수도 있습니다. 이 경우 사용자는 id, first_name, last_name, username, photo_url, auth_date, hash를 쿼리 파라미터로 달고 그 주소로 리디렉션됩니다. 설정 도구의 다른 옵션은 data-size(large, medium, small), data-userpic="false", data-radius, data-request-access="write"입니다.
서버에서 hash 검증하기
검증하기 전에는 받은 데이터를 절대 믿지 마십시오. 알고리즘은 다음과 같습니다. hash를 제외한 모든 필드를 알파벳순으로 정렬하고 key=value 형태로 줄바꿈(\n)으로 이어 data-check-string을 만듭니다. 비밀 키는 봇 토큰의 SHA256(원시 바이트)입니다. 이 키로 data-check-string의 HMAC-SHA-256을 계산하고 16진수 값을 hash와 비교합니다. 그다음 auth_date(Unix 타임스탬프)가 최근인지 확인합니다. 내가 붙인 쿼리 파라미터는 빼고 텔레그램이 보낸 필드만 넘기십시오.
import hashlib
import hmac
import time
def check_telegram_auth(data: dict, bot_token: str, max_age: int = 86400) -> bool:
fields = {k: v for k, v in data.items() if k != "hash"}
data_check_string = "\n".join(f"{k}={fields[k]}" for k in sorted(fields))
secret_key = hashlib.sha256(bot_token.encode()).digest()
calc_hash = hmac.new(secret_key, data_check_string.encode(), hashlib.sha256).hexdigest()
if not hmac.compare_digest(calc_hash, str(data.get("hash", ""))):
return False
return time.time() - int(fields["auth_date"]) <= max_age
# Flask: check_telegram_auth(request.args.to_dict(), BOT_TOKEN)const crypto = require('crypto');
function checkTelegramAuth(data, botToken, maxAgeSec = 86400) {
const { hash, ...fields } = data;
const dataCheckString = Object.keys(fields).sort()
.map((k) => `${k}=${fields[k]}`)
.join('\n');
const secretKey = crypto.createHash('sha256').update(botToken).digest();
const calcHash = crypto.createHmac('sha256', secretKey).update(dataCheckString).digest('hex');
if (typeof hash !== 'string' || hash.length !== calcHash.length) return false;
if (!crypto.timingSafeEqual(Buffer.from(calcHash), Buffer.from(hash))) return false;
return Date.now() / 1000 - Number(fields.auth_date) <= maxAgeSec;
}
// Express: checkTelegramAuth(req.query, process.env.BOT_TOKEN)hash가 맞지 않는 가장 흔한 원인은 잘못된 토큰입니다. 서버에 있는 토큰이 로그인 봇의 것인지 Bot API Tester의 getMe로 확인하십시오. 반환된 username이 data-telegram-login 값과 같아야 합니다. 토큰을 찾거나 교체해야 한다면 텔레그램 봇 토큰 가이드를 참고하십시오. 이 방식은 Mini App initData 검증과 다르다는 점도 기억해 두십시오. initData는 HMAC과 문자열 WebAppData로 키를 만듭니다.
텔레그램 게시물 임베드
공개 채널이나 그룹의 메시지라면 무엇이든 임베드할 수 있습니다. 게시물의 t.me 링크(예: t.me/durov/43)를 브라우저에서 열고 < > EMBED를 누르거나, 링크를 게시물 위젯 설정 도구에 붙여 넣습니다. 결과는 script 태그 하나입니다.
<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-post="durov/43" data-width="100%"></script>
설정 도구의 옵션은 너비(data-width, 기본값 100%), 작성자 사진(data-userpic="true"는 항상 표시, "false"는 숨김, 생략하면 자동), 강조 색상(13B4C6 같은 16진수 값의 data-color), 다크 테마(data-dark="1", 색상을 함께 지정하면 data-dark-color가 추가될 수 있음)입니다.
디스커션 위젯: 내 사이트에 텔레그램 댓글 달기
디스커션 위젯은 공개 채널의 게시물을 댓글과 함께 보여 줍니다. 댓글이 달린 게시물의 링크를 지정합니다.
<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-discussion="contest/198" data-comments-limit="5"></script>
채널만 지정할 수도 있습니다(data-telegram-discussion="your_channel"). 이렇게 하면 각 글 페이지에 그 페이지 링크를 담은 채널 게시물의 댓글이 표시되며, 채널에 링크를 올리는 즉시 적용됩니다. 이 방식을 쓰려면 페이지 head에 페이지의 정규 URL을 담은 <link rel="canonical" href="%page_url%">가 있어야 합니다. 옵션은 댓글 수(data-comments-limit, 설정 도구에서 3~50), data-height, 이름마다 다른 색을 쓰는 data-colorful="1", data-color, data-dark="1"입니다.
텔레그램 공유 버튼
방문자가 공유 버튼을 누르면 텔레그램이 보낼 채팅, 그룹, 채널을 고르게 하고, 보내기 전에 선택 사항인 텍스트를 수정할 수 있게 해 줍니다. core.telegram.org/widgets/share의 생성기는 다음 코드를 만들어 줍니다.
<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-share-url="https://example.com/article" data-comment="꼭 읽어 보세요!" data-size="large"></script>
data-size를 빼면 중간 크기 버튼이 되고, data-text="notext"를 쓰면 아이콘만 표시됩니다. 직접 디자인한 버튼이 필요하면 두 값을 URL 인코딩해서 https://t.me/share/url?url={url}&text={text}로 링크하십시오.
<a href="https://t.me/share/url?url=https%3A%2F%2Fexample.com%2Farticle&text=Check%20this%20out%21">텔레그램으로 공유</a>
const shareUrl = 'https://t.me/share/url?url=' + encodeURIComponent(location.href)
+ '&text=' + encodeURIComponent(document.title);
document.querySelector('#tg-share').href = shareUrl;
JavaScript 예제처럼 encodeURIComponent를 쓰면 한글 제목도 문제없이 인코딩됩니다.
문제 해결
- 기존 위젯에 "Bot domain invalid"가 표시됨. 도메인이 봇에 연결되지 않았습니다. 해당 봇에 대해 @BotFather에
/setdomain을 보내고 페이지의 정확한 도메인을 입력하십시오. - 새 로그인이 반응하지 않거나 거부됨. 페이지 origin이나 리디렉션 URI가 @BotFather의 Allowed URLs에 없거나,
Cross-Origin-Opener-Policy: same-origin헤더가 팝업을 막고 있습니다. - 위젯이 보이지 않음.
telegram-widget.js는telegram.org에서 로드되어 iframe을 삽입합니다. 게시물, 디스커션, 공유 버튼은t.me에서, 기존 로그인은oauth.telegram.org에서 iframe을 가져옵니다. 엄격한 Content-Security-Policy(script-src,frame-src)나 광고 차단기가 이를 막을 수 있습니다. - hash 불일치. 잘못된 봇 토큰, SHA256 대신 토큰 자체를 키로 사용, data-check-string에 섞인 추가 필드(내가 붙인 쿼리 파라미터), 바뀐 필드 값, 잘못된 구분자가 원인입니다. 구분자는
&가 아니라\n입니다. - 게시물을 임베드할 수 없음. 공개 채널과 공개 그룹의 메시지만 임베드됩니다. 비공개 채팅에는 공개 t.me 링크가 없습니다.
- 글 페이지의 디스커션이 비어 있음. 페이지에 canonical 링크 태그가 있는지, 채널에 올린 링크가 그 정규 URL을 가리키는지 확인하십시오.
다음 단계
- 텔레그램 봇 만들기: 로그인 창에서 사이트를 대표할 봇을 만듭니다.
- 텔레그램 봇 토큰 찾기·확인·폐기: 기존 위젯의 hash 검증에 필요합니다.
- 봇 메시지 속 텔레그램 위젯: Bot API 10.4의 HTML 위젯으로, 이 글과는 다른 기능입니다.
- 공식 문서: core.telegram.org/widgets
자주 묻는 질문
내 웹사이트에 텔레그램 로그인 버튼을 넣으려면 어떻게 하나요?
봇을 하나 정하고 @BotFather Mini App에서 봇을 선택한 뒤 Login Widget으로 들어가, 사이트 origin과 리디렉션 URI를 Allowed URLs에 추가하고 Client ID를 복사합니다. 그다음 data-client-id를 넣은 telegram-login.js 코드를 페이지에 추가하고, 돌려받은 id_token을 서버에서 검증합니다.
기존 텔레그램 로그인 위젯은 아직 지원되나요?
문서는 core.telegram.org/widgets/login-legacy에 보관(archived) 상태로 남아 있습니다. 현재 텔레그램은 Telegram Login 라이브러리와 OpenID Connect 방식을 텔레그램 로그인의 기본 방법으로 안내하므로, 새 프로젝트에는 이쪽을 쓰는 편이 좋습니다.
텔레그램 로그인 위젯 데이터는 서버에서 어떻게 검증하나요?
기존 위젯이라면 hash를 제외한 모든 필드를 알파벳순으로 정렬해 key=value 형식으로 \n으로 이어 data-check-string을 만듭니다. SHA256(bot_token)을 키로 HMAC-SHA-256을 계산해 16진수 결과를 hash와 비교하고, auth_date도 확인합니다. 새 로그인에서는 id_token JWT를 텔레그램 JWKS로 검증합니다.
텔레그램 게시물을 웹사이트에 임베드하려면?
게시물의 t.me 링크(예: t.me/durov/43)를 브라우저에서 열고 EMBED를 누르거나, core.telegram.org/widgets/post의 설정 도구를 쓰면 됩니다. 공개 채널과 공개 그룹의 게시물만 임베드할 수 있습니다.
텔레그램 공유 버튼을 직접 디자인할 수 있나요?
네. https://t.me/share/url?url={url}&text={text}로 링크하고 두 값을 URL 인코딩하면 됩니다. JavaScript에서는 encodeURIComponent를 쓰십시오. text는 선택 사항이며, 사용자가 보내기 전에 수정할 수 있습니다.
관련 가이드
텔레그램 봇 만들기: @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 스위치까지 다룹니다.
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과의 차이를 정리했습니다.