문자 발신번호

문자 발신번호

문자(SMS·LMS·MMS)는 계정에 등록해 승인된 발신번호로만 보낼 수 있습니다. 승인되지 않은 번호를 From 으로 보내면 400 from_not_registered 로 거절됩니다.

발신번호는 콘솔 「문자 › 문자 발신번호」, REST API, MCP 에서 관리합니다. 어디서 등록해도 같은 목록에 들어갑니다.

OAuth 토큰으로 호출할 때 조회는 read:messages, 등록·삭제는 write:messages 권한이 필요합니다.

번호를 발급하면 자동으로 등록됩니다

070번호·대표번호를 발급하면 회선 수 한도 안에서 바로 문자 발신번호로 등록됩니다. 발급 응답의 smsSender 에 결과가 실립니다.

"smsSender": { "registered": true, "senderNumberId": "cmh1sn0000001" }

"smsSender": { "registered": false, "reason": "sender_number_limit_reached" }

registered 가 false 여도 번호 발급은 성공입니다. 그 번호로는 아직 문자를 보낼 수 없으며, reason 을 해결한 뒤 등록 API 로 등록할 수 있습니다.

등록

curl -X POST https://api.claw-ops.com/v1/accounts/$ACCOUNT_ID/sender-numbers \
  -H "Authorization: Bearer $CLAWOPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number": "070-5236-1008"}'

• 이 계정이 한국AI통신에서 개통한 070번호·대표번호만 등록할 수 있습니다.
• 등록하면 바로 승인되어 발송에 쓸 수 있습니다.
• 한 번에 한 번호씩 등록합니다.
• 번호는 하이픈·+82 형식 모두 입력할 수 있습니다.
• 이미 등록된 번호면 409 sender_number_already_registered 를 돌려줍니다. 이 경우 번호는 이미 발송에 쓸 수 있는 상태입니다.
• 다른 통신사업자 명의의 대표번호는 지금 문자 발신번호로 등록할 수 없습니다.

회선 수 한도

070번호·대표번호 발신번호는 명의(개인은 본인확인 정보, 법인은 사업자등록번호)마다 등록할 수 있는 회선 수가 정해져 있습니다.

• 같은 명의로 다른 계정에 등록한 번호도 함께 셉니다.
• 승인 대기 중인 번호도 회선 수에 듭니다.
• 법인은 콘솔에서 종사자 수 증빙을 올려 확인받기 전까지 등록할 수 없습니다.
• 관리번호(최종이용자에게 배정한 번호)는 최종이용자 명의로 따로 셉니다.

목록 조회 응답의 limit 에서 이 계정 명의의 사용 회선 수(used)와 한도(limit), 도달 여부(reached)를 볼 수 있습니다.

목록 조회 응답

{
  "senderNumbers": [
    { "id": "cmh1sn0000001", "number": "07052361008", "type": "070",
      "verificationMethod": "own_provisioned", "status": "approved",
      "createdAt": "2026-10-20T07:02:11.000Z" }
  ],
  "grace": [
    { "number": "07052753809", "expiresAt": "2026-11-03T14:59:59.000Z" }
  ],
  "limit": { "used": 1, "limit": 5, "reached": false }
}

삭제

• 삭제하면 그 번호로는 바로 문자를 보낼 수 없고, 회선 수 한도에서도 빠집니다.
• 유예 기간인 번호도 삭제하면 유예가 함께 끝납니다.
• 번호 자체는 반납되지 않습니다. 전화는 그대로 쓸 수 있습니다.
• API·MCP 로는 한국AI통신에서 개통한 번호(verificationMethod 가 own_provisioned)만 삭제할 수 있습니다. 다른 발신번호는 콘솔에서 삭제합니다.

발신번호 범위를 지정한 API 키

발신번호 범위를 지정한 API 키는 발신번호를 조회만 할 수 있습니다.

• 목록에는 그 키의 범위 안 번호만 보입니다.
• 등록·삭제는 403 api_key_sender_numbers_restricted 로 거절됩니다.
• 등록·삭제는 범위를 지정하지 않은 API 키나 콘솔에서 하세요.

오류 코드