통화 전환

할 수 있는 일

인증한 계정의 진행 중인 통화를 다른 전화번호(상담원·담당 부서 등)로 넘기도록 요청해요. REST API로 만든 통화뿐 아니라 수신 전화와 다른 경로로 시작한 통화도 넘길 수 있어요. 에이전트에 전환 도구를 설정하지 않았어도 돼요.

POST https://api.telloai.io/v1/calls/{callId}/transfer

지금은 즉시 전환(cold)과 전화번호 대상만 지원해요. 전환이 성공하면 AI는 통화에서 빠지고 고객은 입력한 번호와 연결돼요.

헤더

이름	필수	설명
`Authorization`	필수	`Bearer <API_KEY>`
`Content-Type`	필수	`application/json`
`Idempotency-Key`	필수	같은 전환 요청이 두 번 실행되지 않게 하는 키. 1~255자이고 쉼표를 넣을 수 없어요

파라미터

이름	위치	필수	설명
`callId`	경로	필수	넘길 통화의 `c_12345` 형식 id예요
`mode`	본문	필수	문자열 `"cold"`. 즉시 전환이에요
`destination.type`	본문	필수	문자열 `"phone"`. 전화번호로 넘겨요
`destination.target`	본문	필수	넘길 전화번호를 문자열로 넣어요. 아래 번호 규칙을 따라요

curl --request POST "https://api.telloai.io/v1/calls/c_12345/transfer" \
  --header "Authorization: Bearer <API_KEY>" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: transfer-c_12345-001" \
  --data '{"mode":"cold","destination":{"type":"phone","target":"+821012345678"}}'

번호 규칙

target은 JSON 문자열로 보내세요. 숫자로 보내면 400 invalid_transfer_request가 와요.
공백·하이픈·괄호·점은 지우고 처리해요. 맨 앞의 +는 쓸 수 있어요.
+82로 시작하는 한국 번호는 국내 형식으로 바꿔요. +82를 떼고 앞에 0을 붙이고, 뗀 번호가 이미 0으로 시작하면 그대로 둬요. 예를 들어 +821012345678은 01012345678로 넘겨요.
+ 없이 82로 시작하는 10자리 이상 번호도 국가번호가 붙은 것으로 보고 같은 방식으로 바꿔요.
1588·1600처럼 1로 시작하는 8자리 대표번호는 0을 붙이지 않아요. +82 1588-1234는 15881234로 넘겨요.
그 밖의 + 번호는 바꾸지 않아요.
바꾼 뒤의 번호가 숫자 8~15자리가 아니면 400 invalid_transfer_request가 와요.

결과

성공하면 202 Accepted와 접수 시점의 통화 객체가 와요. 별도의 data 봉투는 없어요. 필드 구성은 통화 상세와 같아요.

202는 전환 요청을 접수했다는 뜻이에요. 번호 확인과 연결은 그 뒤에 진행되고, 막히거나 실패해도 오류 응답이 따로 오지 않아요. 결과는 통화 상세를 다시 조회해 확인하세요.

전환 중의 상태

번호로 넘기는 동안 통화 상태는 transferring으로 바뀌지 않아요. transferring은 AI가 상담APP 상담사를 부를 때만 보여요.

단계	상세의 `status`
번호를 확인하고 상대 번호를 호출하는 동안	`inProgress` 그대로예요
전환하지 못했을 때(번호 조건에 막힘·조건 확인 지연·연결 실패)	`inProgress` 그대로예요. AI가 통화를 이어 가요
전환이 성공했을 때	AI가 빠지고 이 통화는 끝나요. 전화 통화는 `completed`가 돼요

받은 번호와 이어진 구간은 별도의 파생 통화로 기록되고, 이 API로는 조회되지 않아요. 브라우저로 연결된 통화(웹콜 등)는 전환이 성공하면 고객과 받은 사람이 같은 통화에서 이야기를 이어 가요. 그래서 그 대화가 끝날 때까지 inProgress로 보일 수 있어요. 전환 성공 여부만 알려 주는 필드는 따로 없어요. endReason은 통화 경로에 따라 다른 값이 남으니 특정 값으로 전환 성공을 판정하지 마세요.

막히거나 실패하면

전환할 번호에는 통화 생성과 같은 번호 허용 조건이 적용돼요.

발신이 금지된 번호로는 넘길 수 없어요.
전용 070 번호가 없는 계정은 수신번호 등록으로 인증한 번호로만 넘길 수 있어요.
크레딧 잔액과 동시 발신 회선, 이번 달 발신 시간 한도도 확인해요.

조건에 막히거나 상대가 받지 않으면 전환하지 않고 AI가 통화를 이어 가요. 일시적인 장애로 조건을 제때 확인하지 못해도 전환하지 않아요. 다만 웹콜에서 「연결이 안 될 때」를 「안내 후 통화 종료」로 골랐다면 연결에 실패했을 때 안내 후 통화가 끝날 수 있어요. 어느 경우든 응답은 이미 202이므로 상세에서 status를 확인하세요.

전환 안내

전환하기 전에 Cascading 에이전트와 크루는 고객에게 「상담사에게 연결하겠습니다.」라고 안내해요. S2S 에이전트는 안내 없이 바로 넘겨요. 지금은 안내 문구를 바꿀 수 없고, 에이전트의 전환 도구에 적은 문구도 쓰지 않아요.

넘길 수 있는 통화

상대가 받아 통화 중(inProgress)인 통화만 넘길 수 있어요. 아직 발신 중(dialing)인 통화처럼 통화 중이 아니면 409 call_not_in_progress가 와요.
completed·noAnswer·failed·cancelled는 이미 끝난 상태예요. 409 call_not_active가 와요.
통화의 source는 따지지 않아요. 수신 전화도 넘길 수 있어요.
전환으로 파생된 통화와 포털 테스트 통화, 다른 계정의 통화, 없는 id는 모두 404 call_not_found예요.
한 통화에서 전환은 한 번만 성공할 수 있어요. 통화가 끝나는 중이거나 다른 전환(이 API 요청이든 AI의 전환 도구든)이 진행 중일 때 온 요청은 202로 접수되지만 실행되지 않아요.
상담APP 상담사가 이미 이어받은 통화처럼 AI가 빠진 통화는 inProgress로 보여도 요청이 아무 효과가 없어요. 이때도 응답은 202예요.

중복 전환 방지

Idempotency-Key는 필수예요. 전환 요청마다 고유한 값을 쓰고, 응답을 받지 못해 같은 요청을 다시 보낼 때만 같은 키를 쓰세요. 키는 계정 범위이고 통화 생성과 같은 키 공간을 써요. 통화 생성에 쓴 키를 전환에 다시 쓰지 마세요. 다른 요청으로 보고 409 idempotency_key_reused를 돌려줄 수 있어요.

상황	결과
처음 보는 키	전환을 요청하고 `202` 응답을 24시간 저장해요
저장된 키 + 같은 통화·같은 번호	저장된 `202`를 그대로 돌려주고 전환을 다시 요청하지 않아요
저장됐거나 처리 중인 키 + 다른 요청	`409 idempotency_key_reused`가 와요. 다른 통화·다른 번호와 통화 생성 요청도 다른 요청이에요
같은 키의 같은 요청이 아직 처리 중	`409 idempotency_in_progress`가 와요
그 밖의 거절(`4xx`·`500`·`503`)	저장하지 않아요. 원인을 해소한 뒤 같은 키로 다시 시도할 수 있어요

같은 번호인지는 번호 규칙대로 바꾼 값으로 비교해요. +821012345678과 010-1234-5678은 같은 번호예요.

202를 받았는데 전환되지 않고 통화가 inProgress로 남았다면 새 키로 다시 요청하세요. 같은 키로 보내면 저장된 202만 다시 오고 전환을 다시 시도하지 않아요. 상대 번호를 호출하는 동안에도 inProgress라서 실패와 구분되지 않아요. 앞선 전환이 끝나기 전에 보낸 요청은 실행되지 않으니 시간을 두고 다시 요청하세요.

전환 요청은 접수됐지만 멱등 응답을 저장하지 못한 경우, 키는 잠시 idempotency_in_progress로 남을 수 있어요. 5분 뒤에는 같은 키도 새 요청으로 처리돼 전환을 다시 요청해요. 이미 202를 받았다면 같은 요청을 다시 보내지 말고 통화 상세로 결과를 확인하세요.

오류

HTTP	코드	대처
`400`	`idempotency_key_required`	`Idempotency-Key` 헤더를 넣으세요
`400`	`invalid_idempotency_key`	쉼표 없는 1~255자 키 하나를 헤더 한 줄로 보내세요
`400`	`invalid_transfer_request`	`mode`·`destination.type`·`target`을 문자열로 보냈는지, 번호가 번호 규칙에 맞는지 확인하세요
`401`	`unauthenticated`	API 키를 확인하세요
`404`	`call_not_found`	현재 계정의 통화 id인지 확인하세요
`409`	`call_not_active`	이미 끝났으니 상세에서 최종 결과를 조회하세요
`409`	`call_not_in_progress`	상대가 받아 `inProgress`가 된 뒤 다시 요청하세요
`422`	`transfer_mode_unsupported`	`mode`는 `"cold"`만 지원해요
`422`	`transfer_destination_unsupported`	`destination.type`은 `"phone"`만 지원해요
`500`	`internal_error`	잠시 뒤 같은 키로 다시 요청하세요. 계속되면 지원팀에 문의하세요
`503`	`voice_gateway_unavailable`	전환 요청을 전달하지 못했어요. 드물게 늦게 전달돼 전환될 수 있으니 통화 상세를 확인한 뒤 같은 키로 다시 요청하세요. 같은 통화는 한 번만 넘어가요

그 밖의 오류는 REST 오류를 보세요.

개요

REST API

SDK

MCP

업무 데이터

A2A

할 수 있는 일

헤더

파라미터

번호 규칙

결과

전환 중의 상태

막히거나 실패하면

전환 안내

넘길 수 있는 통화

중복 전환 방지

오류

관련 문서

​할 수 있는 일

​헤더

​파라미터

​번호 규칙

​결과

​전환 중의 상태

​막히거나 실패하면

​전환 안내

​넘길 수 있는 통화

​중복 전환 방지

​오류

​관련 문서

할 수 있는 일

헤더

파라미터

번호 규칙

결과

전환 중의 상태

막히거나 실패하면

전환 안내

넘길 수 있는 통화

중복 전환 방지

오류

관련 문서