텔레그램 게이트웨이 API — 인증 코드를 텔레그램으로 보내기

게이트웨이 API 란

회원 가입·로그인 때 보내는 인증 코드를 문자(SMS) 대신 텔레그램 메시지로 보내 주는 텔레그램의 유료 서비스입니다. 받는 사람은 텔레그램 앱에서 '인증 코드' 알림으로 코드를 봅니다. 채팅 앱을 만드는 도구가 아니라, 내 서비스의 본인 확인 수단입니다(API 4가지).

항목	내용(공식 안내)
받는 사람 조건	그 전화번호로 텔레그램을 쓰고 있어야 한다
가격	코드 1건당 0.01달러로 안내 — 바뀔 수 있으니 공식 페이지에서 확인
전달 안 되면	정해진 시간 안에 전달되지 않은 코드는 자동 환불
시험	내 번호로 보내는 시험은 무료
결제	미리 충전해 둔 잔액에서 차감

기본 흐름

1. 게이트웨이 계정(gateway.telegram.org)을 만들고 API 토큰을 받습니다. 토큰은 서버에만 둡니다.
2. (선택) checkSendAbility 로 그 번호에 보낼 수 있는지 먼저 봅니다. 보낼 수 없다는 결과는 요금이 들지 않습니다.
3. sendVerificationMessage 로 코드를 보냅니다. 코드를 내가 정해 넘기거나, 자릿수(4~8)만 정해 텔레그램이 만들게 할 수 있습니다. 유효 시간(30~3600초)도 정합니다.
4. 사용자가 내 화면에 코드를 넣으면, 텔레그램이 코드를 만든 경우 checkVerificationStatus 로 맞는지 확인합니다.
5. 보낸 코드를 거둬들이려면(아직 전달 전) revokeVerificationMessage.

요청은 HTTPS 로 gatewayapi.telegram.org 에 보내고, 토큰은 Authorization 머리(Bearer)로 붙입니다. 전화번호는 국제 형식(E.164, 예 +821012345678)입니다.

상태 읽기

상태	값(예)	뜻
전달 상태	sent · delivered · read · expired · revoked	보냄 · 받음 · 읽음 · 만료 · 거둬들임
확인 상태	code_valid · code_invalid · code_max_attempts_exceeded · expired	맞음 · 틀림 · 시도 횟수 초과 · 만료

전달 보고를 내 서버로 받으려면 보낼 때 callback_url 을 줍니다. 보고가 진짜 텔레그램에서 왔는지는 요청 머리의 서명(X-Request-Signature)을 공식 문서 방식대로 검사합니다 — 미니 앱 서명 검사와 같은 생각입니다(미니 앱 사용자 확인).

텔레그램 로그인 버튼으로 아예 비밀번호·인증 코드를 없애는 길도 있습니다 — 로그인 위젯.