통화 전환 결과

통화를 상담원이나 다른 번호로 넘겼을 때, 그 전환이 어떻게 됐는지가 통화 조회 응답의 transferTo, transferStatus, transferDuration 에 남습니다.

전환을 거는 방법은 전환 걸기 를 보세요.

어디서 받나요

어느 전환이 여기에 기록되나요

전환 걸기

진행 중인 통화를 다른 번호나 SIP 엔드포인트로 넘깁니다.

curl -X POST "https://api.claw-ops.com/v1/accounts/{accountId}/calls/{callId}/actions/transfer" \
  -H "Authorization: Bearer $CLAWOPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "0212345678",
    "mode": "warm",
    "whisper": "예약 변경 문의입니다.",
    "callerIdMode": "original",
    "requestId": "req_9f3c21"
  }'

{ "callId": "CA...", "transferSequence": 1, "status": "initiated", "requestId": "req_9f3c21" }

접수만 하고 즉시 응답합니다. 대상이 받을 때까지 기다리지 않습니다. 진행과 결과는 Status Callback 의 transfer 이벤트로 오고, 응답의 transferSequence 가 그 결과를 아래 transfers 배열에서 찾는 키입니다.

주요 파라미터

전체 파라미터와 오류 코드는 API Reference 의 Calls → 진행 중 통화 전환 에 있습니다.

전환이 실패하면

대상이 받지 않거나 통화 중이면 발신자와의 통화는 그대로 유지됩니다(afterTransfer 기본값 return). 다른 대상으로 다시 걸 수 있습니다.

다만 이어받을 에이전트가 전환 결과를 받을 수 없는 통화 — 콘솔에서 만든 에이전트이거나, 에이전트 연결이 끊긴 경우 — 에서는 return 이 성립하지 않아 통화가 종료됩니다. 전환이 있었다는 사실을 모르는 에이전트가 맥락 없이 대화를 잇게 되기 때문입니다. 그때는 통화 이벤트에 transfer.after_transfer_downgraded 가 남습니다.

끊기 전에 안내하기

통화가 종료되는 경우(afterTransfer: "terminate", 또는 위처럼 return 이 성립하지 않은 경우) 발신자는 아무 말도 듣지 못한 채 끊깁니다. failureMessage 를 주면 끊기 전에 그 문장을 발신자에게 들려줍니다.

{
  "to": "0212345678",
  "afterTransfer": "terminate",
  "failureMessage": "죄송합니다. 담당자와 연결되지 않았습니다. 잠시 후 다시 걸어 주세요."
}

재생이 끝나면 통화가 종료됩니다. 발신자가 재생 도중에 끊으면 거기서 끝납니다 — transferStatus (no-answer·busy 등)는 안내와 무관하게 그대로 남고, Status Callback 의 transfer 이벤트는 안내를 기다리지 않고 먼저 나갑니다. 문장은 200자까지이며, failureVoice 를 주지 않으면 무료 기본 음성으로 읽습니다(whisperVoice 와 같은 형식).

재시도

응답이 지연돼 503 transfer_timeout 을 받은 경우 전환은 진행 중일 수 있습니다. 같은 requestId 로 재시도하면 중복 전환 없이 먼저 접수된 전환의 transferSequence 를 돌려줍니다.

<Dial> 은 다릅니다

VoiceML 의 <Dial> 은 통화 중에 다른 목적지를 붙이는 것이지, 통화를 넘기고 빠지는 전환이 아닙니다. 그래서 위 transfer* 필드에는 아무것도 남지 않습니다. 결과는 두 가지로 받습니다.

필드

transferStatus 값

다단계 전환과 재시도

한 통화에서 전환을 여러 번 시도할 수 있습니다. 1번 상담원이 받지 않아 2번으로 넘기는 경우입니다. 이때 transfers 에는 시도마다 한 건씩 쌓이고, 위 transfer* 단일 필드는 그중 대표 leg 하나만 보여줍니다.

대표 leg 는 끝난 leg 중 하나입니다. completed 인 leg 가 있으면 그것을, 없으면 sequence 가 가장 큰 leg 를 보여줍니다.

즉 세 번 시도해 마지막에 성공했다면 transferStatus 는 completed 이고 transferTo 는 그 성공한 번호이며, 앞선 두 번의 실패는 transfers 에만 남습니다. 전환 시도를 빠짐없이 보려면 transfers 를 쓰세요.

예시

전환을 두 번 시도해 두 번째에 연결된 통화입니다.

{
  "callId": "CAabcdef1234567890",
  "status": "completed",
  "from": "01012345678",
  "to": "07080588491",
  "direction": "inbound",
  "duration": 184,
  "hangupCause": "normal_clearing",
  "transferTo": "0212345679",
  "transferStatus": "completed",
  "transferDuration": 96,
  "transferHangupCauseQ850": 16,
  "transferSipResponseCode": null,
  "transferReasonText": null,
  "transfers": [
    {
      "sequence": 1,
      "to": "0212345678",
      "mode": "blind",
      "destinationType": "pstn",
      "status": "no-answer",
      "duration": null,
      "billable": false,
      "billableDuration": null,
      "hangupCauseQ850": 19,
      "sipResponseCode": 480,
      "reasonText": null,
      "startedAt": "2026-08-27T04:11:02.000Z",
      "connectedAt": null,
      "endedAt": "2026-08-27T04:11:32.000Z"
    },
    {
      "sequence": 2,
      "to": "0212345679",
      "mode": "blind",
      "destinationType": "pstn",
      "status": "completed",
      "duration": 96,
      "billable": true,
      "billableDuration": 96,
      "hangupCauseQ850": 16,
      "sipResponseCode": null,
      "reasonText": null,
      "startedAt": "2026-08-27T04:11:33.000Z",
      "connectedAt": "2026-08-27T04:11:41.000Z",
      "endedAt": "2026-08-27T04:13:17.000Z"
    }
  ]
}

조회는 통화 ID 로 합니다.

curl "https://api.claw-ops.com/v1/accounts/AC1a2b3c4d/calls/CAabcdef1234567890" \
  -H "Authorization: Bearer sk_..."

통화가 끝나기 전에 알기

위 필드는 통화가 끝난 뒤에 조회해서 봅니다. 전환이 실패했을 때 바로 다른 상담원으로 재시도하거나 안내 문자를 보내려면 Status Callback 의 transfer 이벤트를 쓰세요. 전환 한 건마다 시작, 연결, 종료 순으로 통지됩니다.

transfer 는 기본 이벤트에 포함되지 않습니다. 받으려면 기본 이벤트와 함께 직접 나열해야 합니다.

initiated ringing answered completed transfer

번호의 statusCallbackEvents 또는 발신 요청의 StatusCallbackEvent 에 위 문자열을 그대로 넣으면 됩니다. 통지에 실리는 파라미터는 다음과 같습니다.