← 블로그로 돌아가기

OTP 메시지에 서비스명 표시, 그리고 API 2.1

K-OTP 팀
2026. 10. 20.
announcementapisdk

2026년 10월 20일부터 OTP 메시지에 서비스명을 표시할 수 있습니다. 인증번호는 카카오 알림톡으로만 발송되며(API 2.x), @k-otp/sdk 2.1.0은 호환성을 깨지 않고 새 API를 지원합니다.

메시지에 서비스명 표시

이제 수신자가 어느 서비스의 인증번호인지 알 수 있습니다. 앱에 승인된 서비스명이 있으면 메시지가 [K-OTP] 인증번호는 123456입니다. 3분 내에 입력해주세요. 대신 [K-OTP] 마이앱 인증번호는 123456입니다. 3분 내에 입력해주세요.로 발송됩니다. 기본, 로그인(login), 회원가입(signup), 결제(payment) 모든 템플릿에 적용됩니다.

  • 콘솔에서 설정. 콘솔에서 앱을 열고 설정 탭의 발송 서비스명에 이름을 입력합니다. 미리보기에서 목적별 메시지를 확인할 수 있습니다. 조직 소유자와 관리자만 바꿀 수 있습니다.
  • 1~12자. 한글, 영문, 숫자와 단어 사이 공백 한 칸만 쓸 수 있습니다. 은행, 통신사, 공공기관, 대형 플랫폼, 공식 안내로 오해할 수 있는 이름은 등록할 수 없습니다.
  • K-OTP가 검토. 새로 등록하거나 바꾼 이름은 검토를 거친 뒤에 사용되며, 콘솔에 상태(심사 중, 승인됨, 사유와 함께 반려)가 표시됩니다. 승인 전까지는 서비스명 없이 발송되므로 검토 때문에 발송이 막히지 않습니다.
  • 코드 변경 없음. 같은 templateId를 그대로 쓰면 됩니다. 서비스명은 요청이 아니라 앱에 속하며, 승인되거나 바뀐 이름은 약 1분 안에 반영됩니다. 알림톡 전달에 실패해 SMS로 대체 발송될 때도 같은 문구가 전달됩니다.

자세한 내용은 메시지 템플릿과 서비스명을 참고하세요.

API 2.x: 카카오 알림톡으로만 발송

인증번호는 카카오 알림톡으로 발송됩니다. SMS는 알림톡 전달에 실패했을 때의 자동 대체 발송으로만 남습니다. 대체 발송은 기본으로 켜져 있고 smsFallback: false로 끌 수 있으며, 발송 1건은 그대로 1 크레딧입니다.

POST /v1/issue는 다음 요청을 400 BAD_REQUEST로 거절하고 data.code에 사유를 담으며, 아무것도 발송하지 않습니다.

  • channel: "sms": CHANNEL_NOT_SUPPORTED. channel을 생략하세요. 기본값이 알림톡입니다.
  • false가 아닌 webOtp: WEB_OTP_NOT_SUPPORTED. webOtp를 보내지 마세요.
  • 승인된 알림톡 템플릿이 없는 템플릿: TEMPLATE_NOT_AVAILABLE.

API 2.1.0은 GET /v1/templates의 channelSupport에 있는 "sms"를 지원 중단(deprecated)으로 표시합니다. 2.0.0부터 반환되지 않으며, 다음 major 버전에서 타입에서도 제거됩니다. 채널과 SMS 대체 발송과 API 레퍼런스를 참고하세요.

SDK 2.1.0

@k-otp/sdk 2.1.0은 호환성을 깨는 변경 없이 API 2.x를 지원합니다. 2.0.0용 코드는 그대로 컴파일됩니다.

  • getIssueRequestErrorCode(error)로 400의 CHANNEL_NOT_SUPPORTED, TEMPLATE_NOT_AVAILABLE, WEB_OTP_NOT_SUPPORTED를 읽을 수 있습니다.
  • 지원 중단: channel: "sms", webOtp 옵션과 결과, @k-otp/sdk/ui의 WebOTP 헬퍼와 props. 다음 major 버전에서 제거됩니다.
  • 폼의 webOtp 설정 기본값은 이제 false입니다.

언어별 서버 SDK(C#, Java, Kotlin, PHP, Go, Python, Ruby, Dart)는 API 2.1.0으로 생성한 0.2.0이며 GitHub Releases에서 받을 수 있습니다(Go는 Go 모듈 프록시). SDK와 언어별 서버 SDK를 참고하세요.