전화번호

전화번호는 ClawOps의 통화와 문자가 드나드는 창구입니다. 하나의 번호로 전화를 받고, 전화를 걸고, 문자를 보냅니다. 번호를 발급한 뒤 착신 라우팅을 지정하면 그 번호로 걸려온 전화를 누가 받을지 정해집니다.

번호 객체

발급, 조회, 수정 응답이 모두 같은 형태입니다.

라우팅에 쓰이지 않는 필드는 null로 내려옵니다. 예를 들어 routingType이 agent이면 callFlowId, forwardTo, sipEndpointId, sipCredentialId는 모두 null입니다.

번호 발급

POST /v1/accounts/{accountId}/numbers

본문은 모두 선택이며 {}로 요청해도 발급됩니다. 여기서 지정한 값은 발급된 번호에 그대로 적용됩니다.

$
curl -X POST "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/numbers" \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{}'

1
{
2
  "number": "07012341234",
3
  "numberType": "did",
4
  "source": "pool",
5
  "routingType": "webhook",
6
  "agentId": null,
7
  "callFlowId": null,
8
  "forwardTo": null,
9
  "sipEndpointId": null,
10
  "sipCredentialId": null,
11
  "webhookUrl": null,
12
  "webhookMethod": "POST",
13
  "webhookHeaders": null,
14
  "callContextUrl": null,
15
  "statusCallback": null,
16
  "statusCallbackEvents": null,
17
  "dictionaryId": null,
18
  "createdAt": "2026-08-13T04:12:44.123Z"
19
}

발급 조건

세 가지를 모두 만족해야 발급됩니다.

번호 풀이 비어 있으면 503이 반환됩니다. 이 경우 요청을 바꿔도 결과가 같으므로 잠시 후 다시 시도하세요.

번호 목록 조회

GET /v1/accounts/{accountId}/numbers

$
curl "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/numbers" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

1
{
2
  "data": [
3
    {
4
      "number": "07012341234",
5
      "numberType": "did",
6
      "routingType": "agent",
7
      "agentId": "AG7c2f9b1e4a6d",
8
      "webhookUrl": null,
9
      "createdAt": "2026-08-13T04:12:44.123Z"
10
    }
11
  ]
12
}

착신 라우팅

routingType이 이 번호로 걸려온 전화를 누가 받을지 결정합니다.

라우팅 변경

PUT /v1/accounts/{accountId}/numbers/{number}

경로의 {number}는 번호 그 자체입니다(예: 07012341234). 보낸 필드만 바뀌고 생략한 필드는 그대로 유지됩니다.

에이전트가 받기

$
curl -X PUT "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/numbers/07012341234" \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "routingType": "agent",
>
    "agentId": "AG7c2f9b1e4a6d"
>
  }'

에이전트를 만드는 방법은 에이전트를 참고하세요. 번호에 연결된 에이전트는 삭제할 수 없으므로, 에이전트를 지우려면 먼저 번호의 라우팅을 다른 대상으로 바꿔야 합니다.

콜 플로우가 받기

$
curl -X PUT "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/numbers/07012341234" \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "routingType": "callflow",
>
    "callFlowId": "CF41b8e07d9c25"
>
  }'

내 서버가 받기

$
curl -X PUT "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/numbers/07012341234" \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "routingType": "webhook",
>
    "webhookUrl": "https://my-app.com/voice"
>
  }'

전화가 걸려오면 ClawOps가 이 주소를 호출하고, 응답으로 받은 VoiceML대로 통화를 진행합니다. 주소는 외부에서 접근할 수 있는 HTTP(S)여야 하며 내부망 주소는 거절됩니다.

보유한 다른 번호로 전환

$
curl -X PUT "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/numbers/07012341234" \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "routingType": "forward",
>
    "forwardTo": "07012345678"
>
  }'

SIP와 소프트폰

외부 PBX로 넘기거나(sip) 등록된 소프트폰 단말을 울리려면(softphone) SIP 트렁크 부가서비스가 활성화되어 있어야 합니다.

$
curl -X PUT "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/numbers/07012341234" \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "routingType": "sip",
>
    "sipEndpointId": "SE9d3a5c71f2b8"
>
  }'

엔드포인트는 활성 상태여야 하고 활성 라우트가 하나 이상 있어야 합니다. 소프트폰은 활성화된 등록 단말이어야 하며, 세션용으로 발급한 임시 자격증명은 착신 대상이 될 수 없습니다.

수신 통화 상태 통지

statusCallback을 지정하면 이 번호로 걸려온 통화의 상태 전이를 그 주소로 통지합니다. 거는 통화의 상태는 통화를 생성할 때 지정하는 별도의 statusCallback으로 관리하며, 번호 설정은 관여하지 않습니다.

statusCallbackEvents를 생략하면 initiated ringing answered completed가 적용됩니다.

$
curl -X PUT "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/numbers/07012341234" \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "statusCallback": "https://my-app.com/call-status",
>
    "statusCallbackEvents": "initiated ringing answered completed transfer"
>
  }'

Webhook 헤더 추가

webhookHeaders로 Webhook 호출에 헤더를 덧붙일 수 있습니다. 수신 측에서 요청의 출처를 구분할 때 사용합니다.

1
{
2
  "webhookHeaders": {
3
    "X-Webhook-Token": "tenant-secret-abc123"
4
  }
5
}

null을 보내면 헤더가 제거되고, 필드를 아예 보내지 않으면 그대로 유지됩니다.

받아쓰기 사전 부착

dictionaryId를 지정하면 이 번호로 걸려온 통화의 전사에 해당 사전을 적용합니다. 상호명이나 제품명처럼 잘못 받아쓰기 쉬운 단어를 사전에 등록해 두면 정확도가 올라갑니다.

$
curl -X PUT "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/numbers/07012341234" \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{"dictionaryId": "DC6b41e8f0a92c"}'

부착한 사전은 계정 기본 사전을 대체합니다. 두 사전의 단어가 합쳐지지 않으므로, 기본 사전의 단어도 필요하다면 부착할 사전에 함께 넣어야 합니다. null을 보내면 부착이 해제되고 계정 기본 사전으로 돌아갑니다.

발신번호로 쓰기

전화를 걸거나 문자를 보낼 때 From에는 계정이 보유한 번호만 지정할 수 있습니다. 보유하지 않은 번호를 넣으면 400이 반환되며, 발신번호를 자동으로 골라 주는 동작은 없습니다.

$
curl -X POST "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/calls" \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "To": "01012345678",
>
    "From": "07012341234"
>
  }'

문자 발송의 발신번호 규칙은 문자 메시지를 참고하세요.

대표번호

15xx, 18xx로 시작하는 전국대표번호입니다. 일반 번호와 발급 경로와 제약이 다릅니다.

POST /v1/accounts/{accountId}/representative-numbers

$
curl -X POST "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/representative-numbers" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

응답은 일반 번호와 같은 번호 객체이며 numberType이 representative입니다.

관리번호 발급 링크

내 서비스의 이용자가 직접 방문해 번호를 발급받게 하려면 일회용 발급 링크를 만듭니다. 링크는 한 번만 사용할 수 있고, 사용되거나 만료되면 재사용할 수 없습니다. 관리번호 발급 부가서비스가 필요하며, 자세한 요청과 응답은 API 레퍼런스의 발급 링크 생성을 참고하세요.

번호 반납

DELETE /v1/accounts/{accountId}/numbers/{number}

$
curl -X DELETE "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/numbers/07012341234" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

성공하면 204가 반환되고 본문은 없습니다. 번호는 즉시 풀로 돌아가 다른 계정에 배정될 수 있습니다.

반납해도 그 번호로 주고받은 통화와 문자 이력은 남아 계속 조회할 수 있습니다. 반납한 번호로 forward 하던 다른 번호가 있으면 그 번호는 함께 반납되지 않고 전환 대상만 해제됩니다.

오류

오류 응답에는 항상 error에 사람이 읽을 메시지가 담깁니다.

1
{
2
  "error": "Phone number quota exceeded (3/3)"
3
}