문자 조회 범위를 withinMinutes로 직접 지정할 수 있습니다

문자 메시지 조회 API는 기본적으로 최근 5분 안에 들어온 문자만 찾습니다. 이 범위를 요청할 때마다 원하는 값으로 바꿀 수 있는 withinMinutes 파라미터를 안내드립니다.

왜 필요한가요

인증 안내를 보고 바로 문자를 보내는 사용자만 있는 것은 아닙니다. 화면을 열어둔 채 다른 일을 하다가 몇 분 뒤에 보내는 경우, 문자는 정상적으로 도착했는데도 5분이 지나 조회되지 않아 인증 실패로 처리되곤 했습니다. 반대로 짧은 시간 안에서만 유효해야 하는 절차라면 범위를 좁게 잡는 편이 안전합니다. 어느 쪽이든 서비스 성격에 맞게 정하시면 됩니다.

사용 방법

요청 본문에 withinMinutes를 분 단위 정수로 넣습니다. 1분부터 최대 60분까지 지정할 수 있습니다. 선택값이라 생략하면 기존과 똑같이 5분이 적용되며, 이미 연동해 두신 코드는 고치지 않아도 그대로 동작합니다.

curl -X POST \
  'https://api.octoverse.kr/octomo/v1/public/message/exists' \
  -H 'Accept: application/json' \
  -H 'Authorization: Octomo {API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{ "mobileNum": "01012345678", "text": "OCTOMO 인증 A7K2QF", "withinMinutes": 10 }'

입력값 규칙

• 1분에서 60분 사이의 정수만 받습니다. 이 범위를 벗어난 값은 60으로 줄여서 처리하지 않고 400으로 거절하니, 요청 전에 값을 확인해주세요.
• 정의되지 않은 필드를 함께 보내면 요청 전체가 400으로 거절됩니다. 오타를 조용히 무시하지 않고 바로 알려드리기 위한 동작입니다.
• 생략하면 기본값 5분이 적용됩니다.

이런 때 조정하면 좋습니다

• 인증 화면에 머무는 시간이 긴 서비스 — 10분 안팎으로 넓혀 늦게 보낸 문자도 받아줍니다.
• 결제나 계정 변경처럼 민감한 절차 — 1~2분으로 좁혀 유효 시간을 짧게 가져갑니다.
• 이벤트 응모나 투표처럼 한 번에 몰리는 경우 — 안내 문자를 본 시점과 실제 전송 시점의 간격을 감안해 정합니다.

자세한 요청·응답 형식은 API 문서의 문자 메시지 조회 항목에서 확인하실 수 있고, 테스트 탭에서 값을 바꿔가며 바로 시험해 보실 수 있습니다.