전화번호 발급

{
  "number": "07012340001",
  "source": "pool",
  "webhookUrl": "https://my-app.com/voice",
  "webhookMethod": "POST",
  "callContextUrl": "https://api.example.com/integrations/clawops/call-context",
  "routingType": "webhook",
  "sipEndpointId": null,
  "sipCredentialId": null,
  "forwardTo": null,
  "callFlowId": null,
  "agentId": null,
  "webhookHeaders": {
    "X-Webhook-Token": "tenant-secret-abc123"
  },
  "statusCallback": "https://my-app.com/call-status",
  "statusCallbackEvents": "initiated ringing answered completed transfer",
  "numberType": "did",
  "dictionaryId": null,
  "friendlyName": "고객센터 대표",
  "rejectCallerIdRestricted": false,
  "createdAt": "2024-01-15T09:30:00Z"
}

번호 풀에서 전화번호를 자동 발급합니다. 계정별 번호 할당량(quota)이 설정되어 있으며, 한도 초과 시 422 에러가 반환됩니다.

Authentication

AuthorizationBearer

API Key를 Bearer 토큰으로 전달

Path parameters

accountIdstringRequired

계정 ID

Request

This endpoint expects an object.

webhookUrlstringOptional

수신 전화 처리용 Webhook URL (선택)

webhookMethodenumOptionalDefaults to POST

Webhook HTTP 메서드 (선택, 기본 POST)

Allowed values:

webhookHeadersmap from strings to strings or nullOptional

인바운드 webhook 호출 시 추가될 HTTP 헤더 (선택). 키는 “X-” prefix 필수 (case-insensitive), reserved 헤더(X-Signature, X-Forwarded-*, X-Real-IP) 거절. 최대 10 entries, key ≤ 64 bytes, value ≤ 2048 bytes, ASCII printable.

statusCallbackstring or nullOptional

수신(inbound) 통화 상태 webhook URL (선택). 이 번호로 걸려오는 통화의 상태 전이(ringing → answered → completed[+busy/rejected])를 POST 통지. 발신(outbound)은 통화 생성 시 statusCallback 으로 별도 관리.

statusCallbackEventsstring or nullOptional

구독할 상태 이벤트(공백 구분, 선택). 미지정 시 initiated ringing answered completed 가 적용됩니다. transfer(호전환 진행 상황)는 기본에 포함되지 않으므로 받으려면 직접 나열하세요. 전체 목록은 Webhooks.

Response

번호 발급 성공

numberstringOptional

전화번호

sourcestringOptional

번호 출처 (pool 등)

webhookUrlstring or nullOptional

webhookMethodenumOptional

Allowed values:

callContextUrlstring or nullOptional

routingType=‘agent’에서 Managed Agent 시작 전에 통화별 CallContext를 조회하는 동기 endpoint.

routingTypeenumOptional

Agent 미연결/거부 시 fallback 라우팅. ‘webhook’ = webhookUrl 호출, ‘sip’ = sipEndpointId 의 OriginationRoute 로 외부 PBX 다이얼, ‘softphone’ = sipCredentialId 의 등록 단말로 착신(Kamailio usrloc fork), ‘forward’ = forwardTo(보유 번호)로 내부 착신전환, ‘callflow’ = callFlowId 의 콜 플로우(결정적 ARS)가 인입을 받음, ‘agent’ = agentId 의 매니지드 에이전트가 받음.

sipEndpointIdstring or nullOptional

routingType=‘sip’ 일 때 사용할 SipEndpoint id. 그 외 라우팅에서는 null.

sipCredentialIdstring or nullOptional

routingType=‘softphone’ 일 때 착신할 등록 SIP credential(단말) id. 그 외 라우팅에서는 null.

forwardTostring or nullOptional

routingType=‘forward’ 일 때 내부 착신전환 대상 번호(같은 계정 보유 번호). 그 외 라우팅에서는 null.

callFlowIdstring or nullOptional

routingType=‘callflow’ 일 때 인입을 처리할 콜 플로우 id. 그 외 라우팅에서는 null.

agentIdstring or nullOptional

routingType=‘agent’ 일 때 인입을 처리할 매니지드 에이전트 id. 그 외 라우팅에서는 null.

webhookHeadersmap from strings to strings or nullOptional

Inbound webhook 호출 시 추가될 HTTP 헤더. 키는 “X-” prefix 필수 (case-insensitive), reserved 헤더(X-Signature, X-Forwarded-*, X-Real-IP) 거절. 최대 10 entries, key ≤ 64 bytes, value ≤ 2048 bytes, ASCII printable. null 전송 시 헤더 제거, 미포함 시 변경 없음.

statusCallbackstring or nullOptional

수신(inbound) 통화 상태 webhook URL. 발신은 통화 생성 시 statusCallback 으로 별도 관리.

statusCallbackEventsstring or nullOptional

구독할 상태 이벤트(공백 구분). 미지정 시 initiated ringing answered completed 가 적용됩니다. transfer(호전환 진행 상황)는 기본에 포함되지 않으므로 받으려면 직접 나열하세요.

numberTypeenumOptional

번호 유형. did = 일반 번호, representative = 대표번호.

Allowed values:

dictionaryIdstring or nullOptional

부착된 받아쓰기 사전 id. null 이면 이 번호로 걸려온 통화 전사에 계정 기본 사전을 사용.

friendlyNamestring or nullOptional<=50 characters

번호마다 적어 두는 용도 메모(별칭). null 이면 별칭 없음. 발신 표시·라우팅에는 쓰이지 않습니다.

rejectCallerIdRestrictedbooleanOptional

번호 표시제한 수신 통화를 받지 않고 거절하는지 여부. 기본 false.

createdAtdatetimeOptional

Errors

401

Unauthorized Error

403

Forbidden Error

422

Unprocessable Entity Error

500

Internal Server Error

503

Service Unavailable Error