진행 중 통화 전환
진행 중인 통화를 다른 번호나 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 로 함께 전달되므로, 어느 호출의 결과인지 대조하는 데도 씁니다.
Authentication
API Key를 Bearer 토큰으로 전달
Path parameters
계정 ID
통화 ID
Request
전환 대상. destinationType 이 pstn(기본)이면 전화번호, sip 이면 SIP URI 입니다.
전환 대상 종류. sip 는 SIP 엔드포인트로 직접 연결하며 sip_trunk 부가서비스를 보유한 계정만 사용할 수 있습니다.
blind = 대상이 받으면 바로 연결합니다. warm = 대상이 받으면 whisper 안내를 대상에게만 들려준 뒤 연결합니다. 그동안 발신자는 holdMedia 를 듣습니다.
전환이 끝난 뒤(대상이 받지 않았거나, 연결됐다가 끊긴 뒤) 발신자와의 통화를 어떻게 할지 정합니다. return = 통화를 유지하고 원래 에이전트가 이어받습니다. terminate = 통화를 종료합니다.
return 은 에이전트가 전환 결과를 받을 수 있을 때만 성립합니다. 이어받을 에이전트가 전환이 있었다는 사실을 모르면 맥락 없이 대화를 잇게 되기 때문입니다. 대시보드에서 만든 에이전트가 진행 중인 통화이거나 에이전트 연결이 끊긴 통화에서는 terminate 로 처리되며, 그 사실이 통화 이벤트에 기록됩니다(전환 자체는 그대로 진행됩니다).
전환 대상 단말에 표시할 번호. 계정이 보유한 번호이거나, 통신사망을 통해 직접 걸려 온 통화의 발신자 번호만 지정할 수 있습니다. 그 외에는 403 UNOWNED_CALLER_ID 로 거절됩니다. 생략하면 계정 번호가 표시됩니다. 걸려 온 통화의 발신자 번호를 지정해도 받는 쪽 표시만 바뀝니다 — 통화 자체는 계정 번호에서 넘기는 전환이라, 받는 장비에 따라 계정 번호가 표시될 수 있습니다.
번호 대신 의도로 지정합니다. original = 걸려 온 전화의 발신자 번호를 대상 단말에 표시합니다(통신사망 직수신 인입이고, 그 발신자가 국내 번호인 경우에만 성립). 성립하지 않으면 전환을 실패시키지 않고 계정 번호로 표시합니다. 받는 쪽 표시만 바뀌는 것이라, 받는 장비에 따라 계정 번호가 표시될 수 있습니다.
mode 가 warm 일 때 대상에게만 들려줄 안내 문장. 발신자에게는 들리지 않습니다.
whisper 를 읽을 음성. VoiceML <Say> 의 voice 와 같은 형식입니다 — 생략하면 무료 기본 음성, cartesia:<음성 ID> 를 지정하면 고품질 음성으로 읽고 읽은 글자 수만큼 과금됩니다.
전환이 연결될 때까지 발신자에게 들려줄 대기 음악.
전환이 연결되지 않았을 때(무응답·통화 중·대상 실패) 발신자에게 들려주고 통화를 끝낼 문장. 지정하지 않으면 아무 안내 없이 종료됩니다.
whisper 와 듣는 사람이 반대입니다 — whisper 는 전화를 받은 대상에게만 들립니다.
afterTransfer 가 return 이면 재생되지 않습니다(에이전트가 통화를 이어받습니다). 다만 이어받을 에이전트 연결이 없어 terminate 로 처리된 통화에서는 재생됩니다.
failureMessage 를 읽을 음성. whisperVoice 와 같은 형식입니다 — 생략하면 무료 기본 음성, cartesia:<음성 ID> 를 지정하면 고품질 음성으로 읽고 읽은 글자 수만큼 과금됩니다.
대상의 응답을 기다릴 시간(초).
전환 사유. whisper 안내 문구와 전환 웹훅의 TransferReason 에 함께 쓰입니다.
전환과 함께 전달할 구조화 데이터. 전환 웹훅의 TransferContext 로 모양 그대로 전달됩니다.
호출측 상관 ID. 같은 값의 재요청은 새 전환을 만들지 않으며(멱등), 전환 웹훅에 RequestId 로 되돌아옵니다.
Response
전환 접수됨
대상 통화 ID
이 통화에서 몇 번째 전환인지. 통화 조회 응답의 transfers[].sequence 및 전환 웹훅의 TransferSequence 와 같은 값입니다.
처리 상태
요청에 지정한 상관 ID (지정한 경우에만).