본문으로 건너뛰기
문서 메뉴본인인증 흐름

메신저

본인인증 흐름

비회원은 대화를 시작하기 전에 이름을 적고, 이메일이나 휴대폰 번호를 인증하고, 필수 약관에 동의해야 해요. 인증한 연락처는 회원 가입으로 이어질 수 있어요.

흐름

  1. 고객이 이름을 적고 이메일 또는 휴대폰 번호 중 하나를 고르세요.
  2. verification/start로 6자리 코드를 보내요. 코드는 5분 동안 유효해요.
  3. 고객이 코드를 입력하고 이용약관·개인정보 처리방침에 동의해요. 마케팅 수신 동의는 선택이고 기본값은 체크 해제예요.
  4. verification/confirm이 성공하면 연락처가 인증되고, 채널에 웹훅 contact.verified가 가요.

코드 보내기

요청
POST /v1/messenger/verification/start
Authorization: Bearer <sessionToken>
Content-Type: application/json

{
  "method": "sms",
  "destination": "+821012345678"
}
응답
{
  "challengeId": "chl_01J…",
  "expiresAt": "2026-10-27T09:05:00Z",
  "resendAfterSec": 60
}

method는 email 또는 sms예요. 전화번호는 E.164 형식으로 보내세요. resendAfterSec이 지나기 전에는 다시 보내기 버튼을 막아 두세요.

코드 확인과 동의

요청
POST /v1/messenger/verification/confirm
Authorization: Bearer <sessionToken>
Content-Type: application/json

{
  "challengeId": "chl_01J…",
  "code": "482913",
  "name": "고객",
  "consents": {
    "terms": true,
    "privacy": true,
    "marketing": false,
    "termsVersion": "2026-10"
  }
}
응답
{
  "contact": {
    "id": "ct_01J…",
    "name": "고객",
    "email": null,
    "phone": "+821012345678",
    "phoneVerifiedAt": "2026-10-27T09:01:12Z",
    "consents": {
      "termsAt": "2026-10-27T09:01:12Z",
      "privacyAt": "2026-10-27T09:01:12Z",
      "marketingAt": null,
      "termsVersion": "2026-10"
    }
  },
  "verified": true
}

terms와 privacy가 true가 아니면 확인이 거절돼요. termsVersion에는 고객이 본 약관 버전을 넣으세요. 약관이 바뀌면 다시 동의를 받을 때 이 값으로 구분해요.

제한

인증 코드 제한
항목값
코드6자리 숫자, 5분 유효, 저장할 때는 해시
확인 시도코드 하나당 최대 5번. 넘으면 새 코드를 받아야 해요.
보내기(목적지)같은 이메일·번호로 15분에 5번
보내기(IP)같은 IP에서 1시간에 20번

한도를 넘으면 429 rate_limited를 돌려줘요. 틀린 코드는 otp_invalid, 만료된 코드는 otp_expired, 이미 쓴 코드는 otp_used예요. 자세한 내용은 레이트리밋과 에러 코드를 보세요.