본문 바로가기
텔레그램 한글 가이드
채널·봇 STEP 93 / 99

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

회원 가입·로그인 인증 코드를 문자 대신 텔레그램으로 보내는 게이트웨이 API 를 정리했습니다. 받는 사람 조건과 공식 안내 가격·환불, 토큰과 코드 보내기·확인 흐름, 전달·확인 상태 읽기, 문자와 함께 쓰는 두 단계 설계를 안내합니다.

  • 난이도L4
  • 읽는 시간4분
  • 최종 검증

결론부터

  1. 1인증 코드를 문자 대신 텔레그램으로 — 받는 사람이 텔레그램을 써야 한다.
  2. 2토큰은 서버에, sendVerificationMessage 로 보내고 상태로 확인.
  3. 3텔레그램 먼저, 안 되면 문자로 넘어가는 두 단계로 설계.
이 글의 목차
  1. 게이트웨이 API 란
  2. 기본 흐름
  3. 상태 읽기
  4. 자주 묻는 질문
  5. 한눈에 정리

게이트웨이 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)을 공식 문서 방식대로 검사합니다 — 미니 앱 서명 검사와 같은 생각입니다(미니 앱 사용자 확인).

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

자주 묻는 질문

텔레그램 게이트웨이 API 는 무엇인가요?

회원 인증 코드를 문자 대신 텔레그램 메시지로 보내 주는 텔레그램의 유료 서비스입니다.

텔레그램이 없는 사람에게도 보낼 수 있나요?

없습니다. 먼저 checkSendAbility 로 확인하고, 안 되면 문자로 넘어가게 설계합니다.

가격은 얼마인가요?

공식 페이지는 코드 1건당 0.01달러로 안내합니다. 바뀔 수 있으니 공식 페이지에서 확인합니다.

코드가 전달되지 않으면 돈을 내나요?

정해진 시간 안에 전달되지 않은 코드는 자동 환불된다고 공식 페이지가 안내합니다.

참고한 공식 문서

요약

한눈에 정리

텔레그램 게이트웨이 API — 인증 코드를 텔레그램으로 보내기 한눈에 정리 그림
  1. 1조건

    받는 사람이 텔레그램 사용.

  2. 2흐름

    보내기 · 확인 · 거둬들이기.

  3. 3설계

    텔레그램 → 문자.

이 글 공유하기

같은 문제를 겪는 친구에게 보내 주세요.

텔레그램
더보기

휴대폰으로 열기휴대폰 카메라로 비추면 이 글이 열려요.

최종 수정 2026-10-06

함께 보면 좋은 글

전체 보기 ›