진행 중 통화 전환
진행 중인 통화를 다른 번호나 SIP 엔드포인트로 넘깁니다. 발신자와의 통화는 유지된 채 전환 대상에게 새로 전화를 겁니다.
접수만 하고 즉시 202 로 응답합니다. 대상이 받을 때까지 기다리지 않습니다. 전환의 진행과 결과는 Status Callback 의 transfer 이벤트로 전달되며, 응답의 transferSequence 가 그 결과를 통화 조회 응답의 transfers[] 에서 찾는 키입니다.
transfer 이벤트는 기본 이벤트 집합에 포함되지 않습니다. 발신 시 StatusCallbackEvent 에 직접 나열해야 전환 통지를 받습니다 — 예: initiated ringing answered completed transfer.
어떤 통화에 쓸 수 있나
Voice Agent SDK 또는 대시보드 에이전트가 진행 중인 통화에 사용합니다. VoiceML (<Dial> 등)로 진행 중인 통화는 아직 지원하지 않으며 409 TRANSFER_UNSUPPORTED 로 거절됩니다.
전환이 실패하면
대상이 받지 않거나 통화 중이면 발신자와의 통화는 그대로 유지됩니다(afterTransfer 기본값 return). 다른 대상으로 다시 전환을 걸 수 있습니다. 전환 실패와 함께 통화를 끝내려면 afterTransfer 를 terminate 로 지정하십시오.
다만 이어받을 에이전트가 전환 결과를 받을 수 없는 통화(대시보드 에이전트, 또는 에이전트 연결이 끊긴 경우)에서는 return 이 성립하지 않아 통화가 종료됩니다 — 자세한 조건은 afterTransfer 설명을 보십시오.
재시도
requestId 를 지정하면 같은 값의 재요청은 새 전환을 만들지 않고 먼저 접수된 전환의 transferSequence 를 돌려줍니다. 그 전환이 지금 어떤 상태인지는 통화 조회 응답의 transfers[] 에서 같은 sequence 항목을 보십시오 — 이 응답의 status 는 언제나 접수를 뜻하는 initiated 입니다. 응답이 지연돼 503 을 받은 경우에도 같은 requestId 로 안전하게 재시도할 수 있습니다. 이 값은 전환 결과 웹훅에 RequestId 로 함께 전달되므로, 어느 호출의 결과인지 대조하는 데도 씁니다.
Authorization
BearerAuth API Key를 Bearer 토큰으로 전달
In: header
Path Parameters
계정 ID
통화 ID
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/accounts/AC1a2b3c4d/calls/CA1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6/actions/transfer" \ -H "Content-Type: application/json" \ -d '{ "to": "0212345678", "mode": "warm", "callerIdMode": "original", "whisper": "예약 변경 문의입니다.", "holdMedia": "default", "timeout": 30, "requestId": "req_9f3c21" }'{
"callId": "CA1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6",
"transferSequence": 1,
"status": "initiated",
"requestId": "req_9f3c21"
}{
"error": "string",
"code": "recipient_blocked",
"ip": "52.79.213.41",
"blockers": [
{
"number": "07012340002",
"code": "number_not_carrier_issued",
"message": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다."
}
]
}{
"error": "string",
"code": "recipient_blocked",
"ip": "52.79.213.41",
"blockers": [
{
"number": "07012340002",
"code": "number_not_carrier_issued",
"message": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다."
}
]
}{
"error": "string",
"code": "recipient_blocked",
"ip": "52.79.213.41",
"blockers": [
{
"number": "07012340002",
"code": "number_not_carrier_issued",
"message": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다."
}
]
}{
"error": "string",
"code": "recipient_blocked",
"ip": "52.79.213.41",
"blockers": [
{
"number": "07012340002",
"code": "number_not_carrier_issued",
"message": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다."
}
]
}{
"error": "string",
"code": "recipient_blocked",
"ip": "52.79.213.41",
"blockers": [
{
"number": "07012340002",
"code": "number_not_carrier_issued",
"message": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다."
}
]
}{
"error": "string",
"code": "recipient_blocked",
"ip": "52.79.213.41",
"blockers": [
{
"number": "07012340002",
"code": "number_not_carrier_issued",
"message": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다."
}
]
}{
"error": "string",
"code": "recipient_blocked",
"ip": "52.79.213.41",
"blockers": [
{
"number": "07012340002",
"code": "number_not_carrier_issued",
"message": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다."
}
]
}{
"error": "string",
"code": "recipient_blocked",
"ip": "52.79.213.41",
"blockers": [
{
"number": "07012340002",
"code": "number_not_carrier_issued",
"message": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다."
}
]
}