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

> ## Agent Instructions
> 이 문서는 Telkit 공식 문서예요. 코드를 만들 때는 이 문서에 나온 필드와 엔드포인트만 써 주세요.
> 요금과 기간 숫자는 번호와 요금 쪽(https://telkit.io/docs/numbers/pricing)을 따라 주세요.

# Retell 연동

> Retell의 custom telephony SIP trunking을 거쳐 Telkit 070 번호로 전화를 받고 거는 방법을 단계별로 안내해요.

Retell의 custom telephony SIP trunking을 거쳐 Telkit 070 번호로 전화를 받고 걸어요. 수신과 발신이 모두 돼요.

## 준비물

| 항목 | 설명 |
| - | - |
| Telkit 070 번호 | 번호 구매는 [첫 통화](https://telkit.io/docs/connect/first-call.md)에서 해요. |
| Telkit API 키 | 「API」 탭을 쓸 때만 필요해요. 「에이전트」 탭은 에이전트가 받아요. 직접 받으려면 `POST /v1/connect-links`로 연결 링크를 만들어 열고 가입을 마쳐요. 그다음 응답의 `task_id`로 `GET /v1/human-tasks/{task_id}`를 읽어 `completed`일 때 한 번만 나오는 `result.connect_token`을 Bearer로 `POST /v1/api-keys`에 보내요. 순서는 [영어 에이전트 문서](https://telkit.io/auth.md)에 있어요. |
| 등록한 카드 | 카드가 없으면 발신 접속 정보를 만들 수 없어요. |
| Retell agent | 전화를 받고 걸 음성 에이전트예요. |

## 수신

Telkit 번호로 걸려 온 전화를 Retell 음성 에이전트가 받아요.

### Retell에 Telkit 번호를 가져와요

Retell 대시보드의 **Phone Numbers**에서 **Add number** 메뉴를 열고 **Import via SIP trunking**을 골라 아래처럼 채운 뒤 **Save**를 눌러요. API로는 [Import Phone Number](https://docs.retellai.com/api-references/import-phone-number)에 `phone_number`, `termination_uri`, `transport`를 같은 값으로 보내요. 자세한 칸은 [Retell custom telephony 문서](https://docs.retellai.com/deploy/custom-telephony)를 봐요.

| Retell 칸 | 넣을 값 |
| - | - |
| **Phone Number** | Telkit 070 번호를 `+827012345678` 모양으로 넣어요. |
| **Termination URI** | `sip.telkit.io`. 발신에 쓰는 칸이지만 비워 둘 수 없어 지금 넣어요. |
| **Outbound Transport** | `TLS`. 기본값이 TCP라 바꿔야 해요. |
| **SIP Trunk User Name**, **SIP Trunk Password** | 비워 둬요. 「발신」에서 넣어요. |

가져온 번호를 열고 **Inbound Agent**에 전화를 받을 agent를 골라요. API로는 `inbound_agents`예요. agent를 고르면 번호가 바로 전화를 받을 수 있어요.

**Telkit이 보내는 전화**

| 항목 | 값 |
| - | - |
| 보내는 IP | `34.64.81.145`, `34.47.68.103`. 두 개를 모두 허용해요. |
| 신호 | TLS 5061, UDP·TCP 5080 |
| 음성 | RTP, UDP 30000 \~ 40000 |
| 인증 | 아이디와 비밀번호를 보내지 못해요. 위 IP로 받거나 인증 없이 받아요. |
| 음성 암호화 | 기본은 TLS 위 SDES SRTP예요. 받는 쪽이 SRTP를 받지 않으면 번호 연결의 `srtp`를 `none`으로 해 주세요. |
| 번호 형식 | 기본은 `07012345678`이고, 번호 연결의 `number_format`을 `e164`로 하면 `+827012345678`로 보내요. 거는 사람 번호도 같은 형식이에요. |
| 받는 번호가 실리는 곳 | Request-URI와 `To` 헤더에 위 번호 형식으로 똑같이 실려요. 연결 주소에 `@` 앞부분이 있으면(`sip:이름@호스트`) 두 곳에 번호 대신 그 이름이 실려요. `X-Telkit-DID` 헤더에는 언제나 `+827012345678`로 실려요. |

Retell 문서는 들어오는 전화를 IP나 아이디로 막는 설정을 안내하지 않아요. 그래서 Retell 쪽에는 위 값을 넣지 않아요.

### Telkit 번호를 Retell로 넘겨요

Retell의 SIP 주소는 `sip:sip.retellai.com` 하나이고, 전송은 주소 끝의 `;transport=`로 골라요. 사용자 없이 이 주소를 넣고 번호 형식을 E.164로 하면, Telkit이 받은 070 번호를 `+827012345678` 모양으로 앞에 붙여 보내요. Retell은 SRTP를 TLS에서만 받으므로 전송은 TLS, `srtp`는 기본값인 `sdes`로 둬요.

> [tab] 에이전트
>
> Telkit 070 번호로 걸려 온 전화를 Retell SIP 주소로 넘기는 한 줄이에요.
>
> [https://telkit.io/llms.txt](https://telkit.io/llms.txt) 를 읽고 내 070 번호로 걸려 온 전화가 sip:sip.retellai.com;transport=tls 로 가게 해 줘. 전송은 TLS, srtp는 sdes, 번호 형식은 E.164로 해 줘.

> [tab] API
>
> `$NUMBER_ID`는 `GET /v1/numbers`가 돌려주는 번호의 `id`예요.
>
> ```bash theme={null}
> curl -s -X PUT "https://api.telkit.io/v1/numbers/$NUMBER_ID/connection" \
>   -H "Authorization: Bearer $TELKIT_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"sip_uri":"sip:sip.retellai.com;transport=tls","transport":"tls","srtp":"sdes","number_format":"e164"}'
> ```
>
> 응답의 `updated_at`에서 1분이 지나면 새 주소로 전화가 가요.

### 시험 통화를 걸어요

내 휴대폰으로 070 번호에 전화를 걸어요. Retell 음성 에이전트가 받으면 끝나요. 주소를 저장하고 1분이 지나기 전에 걸면 끊길 수 있어요.

## 발신

Retell 음성 에이전트가 Telkit 070 번호로 전화를 걸어요.

### 발신 접속 정보를 받아요

> [tab] 에이전트
>
> Telkit 070 번호의 발신 접속 정보를 만드는 한 줄이에요.
>
> [https://telkit.io/llms.txt](https://telkit.io/llms.txt) 를 읽고 내 070 번호의 발신 접속 정보를 만들어서 사용자 이름과 비밀번호를 알려 줘.

> [tab] API
>
> 먼저 `GET /v1/sip-trunk`로 이 번호의 `state`를 읽어요. `card_required`이면 카드 등록 링크로 카드를 등록하고, `preparing`이면 1분 기다렸다가 다시 읽어요. `auth_required`이면 아래 비밀번호를 만들어요.
>
> ```bash theme={null}
> curl -s "https://api.telkit.io/v1/sip-trunk" \
>   -H "Authorization: Bearer $TELKIT_API_KEY"
>
> curl -s -X POST "https://api.telkit.io/v1/numbers/$NUMBER_ID/sip-credential" \
>   -H "Authorization: Bearer $TELKIT_API_KEY"
> ```
>
> 응답의 `username`과 `password`가 아래 표의 「에이전트가 건네준 값」이에요. 비밀번호는 한 번만 보여요.

**Telkit으로 거는 전화**

| 항목 | 값 |
| - | - |
| 주소 | `sip.telkit.io` |
| 포트 | `5061` |
| 전송 | TLS만 돼요. |
| 오디오 | G.711인 `PCMA`와 `PCMU`만 받아요. Opus만 제안하면 거절해요. |
| 미디어 암호화 | SDES 방식 SRTP를 권해요. 평문 RTP도 받아요. |
| 등록 | `REGISTER`는 받지 않고 전화마다 인증을 보내요. |
| 사용자 이름 | 에이전트가 건네준 값 |
| 비밀번호 | 에이전트가 건네준 값. 한 번만 보여요. |
| 보내는 번호 | 내 070 번호예요. `07012345678`, `827012345678`, `+827012345678`이 모두 돼요. |
| 받는 번호 | `+821012345678`, `821012345678`, `01012345678`이 모두 돼요. |

### Retell 번호에 접속 정보를 넣어요

Retell에는 따로 거는 주소가 없고, 가져온 번호의 설정에 Telkit 주소와 인증 정보를 넣어요. **Phone Numbers**에서 가져온 번호를 고르고 **…** 메뉴의 **Edit Phone Number Settings**를 열어 아래처럼 채운 뒤 **Save**를 눌러요.

| Retell 칸 | 넣을 값 |
| - | - |
| **Termination URI** | `sip.telkit.io` |
| **Outbound Transport** | `TLS` |
| **SIP Trunk User Name**, **SIP Trunk Password** | 에이전트가 건네준 값 |

가져온 번호의 **Outbound Agent**에 전화를 걸 agent를 골라요.

**Test SIP Connection**은 Termination URI로 SIP OPTIONS 요청만 보내요. 성공해도 실제 전화와 소리까지 확인한 것은 아니니 다음 단계의 시험 통화로 확인해요.

### 시험 통화를 걸어요

비밀번호를 만들고 1 \~ 2분 뒤에 Retell에서 내 휴대폰으로 전화를 걸어요. 대시보드에서 걸거나 Create Phone Call API에 `from_number`는 내 070 번호, `to_number`는 `+821012345678` 모양으로 보내요. 휴대폰에 내 070 번호가 뜨고 음성 에이전트가 말하면 끝나요. 방법은 [Retell 발신 문서](https://docs.retellai.com/deploy/outbound-call)를 봐요.

## 문제 해결

| 증상 | 할 일 |
| - | - |
| 수신 전화가 바로 끊겨요 | 주소를 저장하고 1분이 지났는지 봐요. Retell에 가져온 번호가 `+82`로 시작하는지, Telkit 번호 연결의 번호 형식이 E.164인지, 번호에 **Inbound Agent**를 골랐는지 봐요. |
| 수신 전화가 `488`로 거절돼요 | 번호 설정의 **Codecs**에서 PCMU와 PCMA가 켜져 있는지 봐요. |
| 발신 접속 정보를 만들 수 없어요 | 카드를 등록했는지, 번호의 발신이 열렸는지 에이전트에게 확인해 달라고 해요. 카드가 없거나 발신이 열리는 중이면 만들 수 없어요. |
| 발신이 거절돼요 | 비밀번호를 만들고 1 \~ 2분이 지났는지, **Outbound Transport**가 `TLS`인지, 사용자 이름과 비밀번호가 에이전트가 건네준 값과 같은지 봐요. 비밀번호를 잃었으면 에이전트에게 새로 만들어 달라고 해요. |
| 통화가 막혀요 | [한도와 동시 통화](https://telkit.io/docs/numbers/limits.md)를 확인해요. |

더 있다면 [문제 해결](https://telkit.io/docs/troubleshooting.md)을 봐 주세요.

## 관련 쪽

> [card] [지원 플랫폼](https://telkit.io/docs/connect/platforms.md)
>
> 수신과 발신이 되는 플랫폼을 한눈에 봐요.

> [card] [한도와 동시 통화](https://telkit.io/docs/numbers/limits.md)
>
> 통화가 막혔을 때 한도를 확인해요.

> [card] [Retell custom telephony 문서](https://docs.retellai.com/deploy/custom-telephony)
>
> Retell의 SIP trunking 문서예요.

> [card] [에이전트에게 맡기기](https://telkit.io/docs/connect/agent.md)
>
> 이 연결을 에이전트에게 통째로 맡겨요.


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