API를 통해 번호 구매 및 문자 메시지 등록

API는 구매 가능한 전화번호를 검색하고 구매하며, 10DLC 문자 메시지 등록을 위해 비즈니스를 등록할 수 있습니다. 이는 앱에서 수행하는 것과 동일한 청구, 요구 사항 및 결과를 제공합니다. POST /v1/api/numbers를 통해 구매한 번호는 설정 → 번호에 즉시 나타나며, API를 통해 신청된 등록은 문자 메시지 설정 카드에 표시되므로 언제든지 앱에서 관리할 수 있습니다.

시작하기 전에

• API 키에는 numbers:manage 범위가 필요합니다. 이는 설정 → 개발자 API의 번호 구매 및 10DLC 칩입니다. 전체 액세스 키에는 자동으로 포함됩니다. Ody API 키 가져오기를 참조하세요.
• 앱과 동일한 규칙이 적용됩니다. 워크스페이스는 구매를 위해 활성 요금제가 필요하며, Ody가 신원 확인을 요청한 경우 먼저 완료해야 합니다. 완료될 때까지 API는 409 failed_precondition을 반환합니다.
• 청구는 인앱과 동일합니다. 요금제에는 하나의 번호가 포함되며, 추가 번호는 월 $5의 추가 번호 애드온으로 청구됩니다. 추가 번호 추가를 참조하세요.

사용 가능한 번호 검색

GET /v1/api/numbers/available는 구매할 수 있는 번호를 검색합니다. country (기본값 US), startsWith (예: 지역 코드), contains, locality, state, limit (기본값 20, 최대 50)으로 필터링할 수 있습니다.

curl "https://api.ody.co/v1/api/numbers/available?startsWith=512&limit=5" \
  -H "Authorization: Bearer ody_live_…"

각 후보는 해당 번호와 Ody에 실제로 지불할 월별 가격을 포함합니다.

{
  "available": [
    {
      "phone_number": "+15125550123",
      "cost_information": { "monthly_cost": "5.00", "upfront_cost": "0.00", "currency": "USD" }
    }
  ]
}

번호 구매

POST /v1/api/numbers는 검색 결과에서 번호를 주문합니다. 네트워크 재시도가 번호를 두 번 구매하는 것을 방지하기 위해 Idempotency-Key 헤더를 전송하세요. 24시간 이내의 재시도는 Idempotency-Replayed: true 헤더와 함께 원래 응답을 다시 재생합니다.

curl https://api.ody.co/v1/api/numbers \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: onboarding-main-line" \
  -d '{"phoneNumber":"+15125550123"}'

번호는 주문되어 워크스페이스에 추가되고 기존 구독에 청구됩니다. 이는 앱에서 구매를 클릭하는 것과 동일합니다. 설정 → 번호에 즉시 나타나며, 다른 번호와 마찬가지로 귀하(또는 귀하의 팀)가 착신 순서, 음성 메일, 전화 메뉴 또는 AI 에이전트를 구성할 수 있습니다. 통화는 즉시 작동하며, 지역 번호로 문자 메시지를 보내는 것은 10DLC 등록이 승인될 때까지 제한됩니다(아래 참조).

문자 메시지 등록 (10DLC)

미국 통신사는 지역 번호로 문자 메시지를 보내기 전에 비즈니스 등록을 요구합니다. API는 인앱 문자 메시지 설정 흐름을 반영합니다.

GET /v1/api/messaging으로 상태를 확인하세요. 응답의 step은 비즈니스(브랜드) 검토와 캠페인 검토를 안내하며, 통신사가 승인하는 순간 canText가 true로 전환됩니다. 그러면 앱과 API 모두에서 문자 메시지가 작동합니다.

POST /v1/api/messaging/registration으로 등록을 제출하세요. business 블록에는 displayName, email, vertical, street, city, state, postalCode가 필요하며, 개인 사업자(entityType: "SOLE_PROPRIETOR", firstName, lastName, 연락처 전화번호 사용)로 등록하지 않는 한 법적 companyName과 EIN도 필요합니다. campaign 블록은 선택 사항이며, 합리적인 기본값(규정을 준수하는 STOP/HELP 처리가 포함된 혼합 사용 사례)이 적용됩니다.

curl https://api.ody.co/v1/api/messaging/registration \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "business": {
      "displayName": "Acme Plumbing",
      "email": "[email protected]",
      "vertical": "PROFESSIONAL",
      "companyName": "Acme Plumbing LLC",
      "ein": "12-3456789",
      "street": "600 Congress Ave",
      "city": "Austin",
      "state": "TX",
      "postalCode": "78701"
    },
    "campaign": {
      "description": "Customer care and appointment notifications",
      "samples": ["Acme Plumbing: your appointment is confirmed for Tuesday at 9am."]
    }
  }'

API를 통한 신청은 $20의 일회성 등록비를 포함하여 인앱 신청과 동일하게 청구됩니다. POST /v1/api/messaging/refresh를 사용하여 통신사 검토를 다시 확인하고 파이프라인을 진행하세요. 승인도 자동으로 진행됩니다.

AI 어시스턴트(MCP)에서

동일한 기능이 MCP 도구로 제공되므로 연결된 어시스턴트가 이 전체 흐름을 실행할 수 있습니다: search_numbers, buy_number, get_messaging_status, submit_10dlc_registration. MCP로 AI 도구 연결을 참조하세요.

테스트 모드

ody_test_… 키를 사용하면 POST /numbers가 시뮬레이션된 구매("simulated": true)를 반환합니다. 아무것도 주문되거나 프로비저닝되거나 청구되지 않으며, 10DLC 등록은 모의 모드로 신청됩니다. 전체 파이프라인이 레지스트리 제출 및 수수료 없이 실행됩니다. 테스트 모드로 안전하게 구축을 참조하세요.

관련 문서

• 전화번호 구매
• 10DLC 메시지 등록
• API를 통해 AI 통화 걸기 및 Astra 관리
• 테스트 모드로 안전하게 구축

---