> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telloai.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 통화 전환

> 진행 중인 통화를 다른 전화번호로 넘기도록 요청하고, 상세 조회로 결과를 확인해요.

## 할 수 있는 일

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

```http theme={null}
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` | 본문 | 필수 | 넘길 전화번호를 **문자열**로 넣어요. 아래 번호 규칙을 따라요 |

```bash theme={null}
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` 봉투는 없어요.
필드 구성은 [통화 상세](https://docs.telloai.io/developer/rest/get-call.md)와 같아요.

> [!WARNING]
>
> `202`는 전환 요청을 접수했다는 뜻이에요. 번호 확인과 연결은 그 뒤에 진행되고, 막히거나
> 실패해도 오류 응답이 따로 오지 않아요. **결과는 [통화 상세](https://docs.telloai.io/developer/rest/get-call.md)를 다시
> 조회해 확인하세요.**

### 전환 중의 상태

번호로 넘기는 동안 통화 상태는 `transferring`으로 바뀌지 않아요. `transferring`은 AI가
[상담APP](https://docs.telloai.io/channels/agent-app.md) 상담사를 부를 때만 보여요.

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

받은 번호와 이어진 구간은 별도의 파생 통화로 기록되고, 이 API로는 조회되지 않아요. 브라우저로
연결된 통화(웹콜 등)는 전환이 성공하면 고객과 받은 사람이 같은 통화에서 이야기를 이어 가요.
그래서 그 대화가 끝날 때까지 `inProgress`로 보일 수 있어요.

전환 성공 여부만 알려 주는 필드는 따로 없어요. `endReason`은 통화 경로에 따라 다른 값이 남으니
특정 값으로 전환 성공을 판정하지 마세요.

### 막히거나 실패하면

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

* 발신이 금지된 번호로는 넘길 수 없어요.
* 전용 070 번호가 없는 계정은 [수신번호 등록](https://docs.telloai.io/calls/caller-id.md)으로 인증한 번호로만 넘길 수 있어요.
* 크레딧 잔액과 동시 발신 회선, 이번 달 발신 시간 한도도 확인해요.

조건에 막히거나 상대가 받지 않으면 전환하지 않고 AI가 통화를 이어 가요. 일시적인 장애로 조건을
제때 확인하지 못해도 전환하지 않아요. 다만
[웹콜](https://docs.telloai.io/channels/overview.md#웹콜-채널)에서 「연결이 안 될 때」를 「안내 후 통화 종료」로 골랐다면
연결에 실패했을 때 안내 후 통화가 끝날 수 있어요. 어느 경우든 응답은 이미 `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](https://docs.telloai.io/channels/agent-app.md) 상담사가 이미 이어받은 통화처럼 AI가 빠진 통화는 `inProgress`로
  보여도 요청이 아무 효과가 없어요. 이때도 응답은 `202`예요.

## 중복 전환 방지

`Idempotency-Key`는 필수예요. 전환 요청마다 고유한 값을 쓰고, **응답을 받지 못해 같은 요청을
다시 보낼 때만 같은 키**를 쓰세요. 키는 계정 범위이고
[통화 생성](https://docs.telloai.io/developer/rest/create-call.md#중복-발신-방지)과 같은 키 공간을 써요. 통화 생성에 쓴
키를 전환에 다시 쓰지 마세요. 다른 요청으로 보고 `409 idempotency_key_reused`를 돌려줄 수 있어요.

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

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

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

> [!WARNING]
>
> 전환 요청은 접수됐지만 멱등 응답을 저장하지 못한 경우, 키는 잠시 `idempotency_in_progress`로
> 남을 수 있어요. 5분 뒤에는 같은 키도 새 요청으로 처리돼 전환을 다시 요청해요. 이미 `202`를
> 받았다면 같은 요청을 다시 보내지 말고 [통화 상세](https://docs.telloai.io/developer/rest/get-call.md)로 결과를 확인하세요.

## 오류

| 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` | 전환 요청을 전달하지 못했어요. 드물게 늦게 전달돼 전환될 수 있으니 [통화 상세](https://docs.telloai.io/developer/rest/get-call.md)를 확인한 뒤 같은 키로 다시 요청하세요. 같은 통화는 한 번만 넘어가요 |

그 밖의 오류는 [REST 오류](https://docs.telloai.io/developer/rest/errors.md)를 보세요.

## 관련 문서

* [통화 상세](https://docs.telloai.io/developer/rest/get-call.md)
* [통화 종료](https://docs.telloai.io/developer/rest/end-call.md)
* [통화 생성](https://docs.telloai.io/developer/rest/create-call.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.