> ## 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)을 따라 주세요.

# LiveKit 연동

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

LiveKit의 SIP를 거쳐 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)에 있어요. |
| 등록한 카드 | 카드가 없으면 발신 접속 정보를 만들 수 없어요. |
| LiveKit Cloud 프로젝트 | SIP URI는 LiveKit Cloud의 **Project settings**에서 확인해요. `sip:vjnxecm0tjk.sip.livekit.cloud` 모양이에요. |
| LiveKit 음성 에이전트 | 전화를 받고 걸 음성 에이전트예요. 없으면 [LiveKit Voice AI quickstart](https://docs.livekit.io/agents/start/voice-ai/)로 만들어요. |

## 수신

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

### LiveKit에서 inbound trunk를 만들어요

LiveKit Cloud에서 **Telephony** → **SIP trunks** → **Create new trunk**를 고르고 **JSON editor** 탭을 열어요. **Trunk direction**은 **Inbound**로 고르고 아래 칸을 넣은 뒤 **Create**를 눌러요. 자세한 칸은 [LiveKit inbound trunk 문서](https://docs.livekit.io/telephony/accepting-calls/inbound-trunk/)를 봐요.

| LiveKit 칸 | 넣을 값 |
| - | - |
| `name` | 알아보기 쉬운 이름을 넣어요. |
| `numbers` | Telkit 070 번호를 `+827012345678` 모양으로 넣어요. |
| `auth_username`, `auth_password` | 넣지 않아요. Telkit은 아이디와 비밀번호를 보내지 못해요. |
| `allowed_addresses` | 아래 표의 보내는 IP 두 개를 넣어요. 이 칸은 LiveKit 지원팀이 프로젝트에서 켜 준 뒤에만 적용되고, 그 전에는 저장만 돼요. |
| `media`의 `encryption` | `SIP_MEDIA_ENCRYPT_ALLOW`. LiveKit은 기본으로 음성 암호화가 꺼져 있어요. |

LiveKit [보안 트렁킹 문서](https://docs.livekit.io/telephony/features/secure-trunking/) 예시의 `media_encryption`은 같은 설정의 예전 이름이에요. 음성 암호화를 켜지 않으려면 3단계에서 `srtp`를 `none`으로 보내요.

**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`로 실려요. |

### dispatch rule을 만들어요

LiveKit Cloud에서 **Telephony** → **Dispatch rules** → **Create new dispatch rule**을 고르고 **JSON editor** 탭에 아래 칸을 넣은 뒤 **Create**를 눌러요. 칸은 [LiveKit dispatch rule 문서](https://docs.livekit.io/telephony/accepting-calls/dispatch-rule/)를 봐요.

| LiveKit 칸 | 넣을 값 |
| - | - |
| `name` | 알아보기 쉬운 이름을 넣어요. |
| `rule` | `dispatch_rule_individual`에 `room_prefix`를 `call-`처럼 넣어요. 전화마다 새 room이 생겨요. |
| `room_config`의 `agents` | 음성 에이전트의 `agent_name`을 넣어요. 음성 에이전트 코드에 등록한 이름과 같아야 해요. |

### Telkit 번호를 LiveKit으로 넘겨요

아래 주소를 준비물에서 확인한 내 SIP URI로 바꿔서 써요.

> [tab] 에이전트
>
> Telkit 070 번호로 걸려 온 전화를 LiveKit SIP URI로 넘기는 한 줄이에요.
>
> [https://telkit.io/llms.txt](https://telkit.io/llms.txt) 를 읽고 내 070 번호로 걸려 온 전화가 sip:vjnxecm0tjk.sip.livekit.cloud 로 가게 해 줘. 전송은 TLS, 음성 암호화는 SRTP, 번호 형식은 E.164로 해 줘.

> [tab] API
>
> ```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:vjnxecm0tjk.sip.livekit.cloud","transport":"tls","srtp":"sdes","number_format":"e164"}'
> ```
>
> 응답의 `updated_at`에서 1분이 지나면 새 주소로 전화가 가요.

### 시험 통화를 걸어요

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

## 발신

LiveKit 음성 에이전트가 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`이 모두 돼요. |

### LiveKit에서 outbound trunk를 만들어요

LiveKit Cloud에서 **Telephony** → **SIP trunks** → **Create new trunk**를 고르고 **JSON editor** 탭을 열어요. **Trunk direction**은 **Outbound**로 고르고 위 값을 아래 칸에 넣은 뒤 **Create**를 눌러요. 자세한 칸은 [LiveKit outbound trunk 문서](https://docs.livekit.io/telephony/making-calls/outbound-trunk/)를 봐요.

| LiveKit 칸 | 넣을 값 |
| - | - |
| `name` | 알아보기 쉬운 이름을 넣어요. |
| `address` | `sip.telkit.io`. LiveKit은 이 칸에 호스트 이름이나 IP만 받아요. `sip:`와 포트를 붙이지 않아요. |
| `transport` | `SIP_TRANSPORT_TLS` |
| `numbers` | Telkit 070 번호를 `+827012345678` 모양으로 넣어요. |
| `auth_username`, `auth_password` | 에이전트가 건네준 값 |
| `media`의 `encryption` | `SIP_MEDIA_ENCRYPT_ALLOW` |

### 시험 통화를 걸어요

비밀번호를 만들고 1 \~ 2분 뒤에 음성 에이전트가 `CreateSIPParticipant`로 내 휴대폰에 전화를 걸게 해요. 요청의 `sip_trunk_id`에는 2단계 outbound trunk의 ID를, `sip_call_to`에는 내 휴대폰 번호를 `+821012345678` 모양으로 넣어요. 휴대폰에 내 070 번호가 뜨고 음성 에이전트가 말하면 끝나요. 음성 에이전트가 거는 코드는 [LiveKit 발신 문서](https://docs.livekit.io/telephony/making-calls/outbound-calls/)를 봐요.

## 문제 해결

| 증상 | 할 일 |
| - | - |
| 수신 전화가 바로 끊겨요 | 번호 연결을 저장하고 1분이 지났는지 봐요. inbound trunk `numbers`의 번호 모양이 Telkit 번호 형식과 같은지 맞춰요. `+82`로 넣었다면 번호 형식은 E.164예요. |
| 수신 전화가 연결되지 않아요 | inbound trunk의 `media`의 `encryption`이 `SIP_MEDIA_ENCRYPT_ALLOW`인지 봐요. 음성 암호화를 끈 채로 쓰려면 Telkit 번호 연결의 `srtp`를 `none`으로 바꿔요. |
| 전화가 울리지만 음성 에이전트가 받지 않아요 | 음성 에이전트가 실행 중인지, dispatch rule의 `agent_name`이 음성 에이전트 코드에 등록한 이름과 같은지 봐요. |
| 발신 접속 정보를 만들 수 없어요 | 카드를 등록했는지, 번호의 발신이 열렸는지 에이전트에게 확인해 달라고 해요. 카드가 없거나 발신이 열리는 중이면 만들 수 없어요. |
| 발신이 거절돼요 | 비밀번호를 만들고 1 \~ 2분이 지났는지, 사용자 이름과 비밀번호가 에이전트가 건네준 값과 같은지, outbound trunk `numbers`의 번호가 내 070 번호인지 봐요. 비밀번호를 잃었으면 에이전트에게 새로 만들어 달라고 해요. |
| 발신이 연결되지 않아요 | outbound trunk의 `media`에서 `only_listed_codecs`를 켰다면 `codecs`에 `PCMU`나 `PCMA`가 들어 있는지 봐요. Opus만 남기면 거절돼요. |
| 통화가 막혀요 | [한도와 동시 통화](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] [LiveKit SIP 문서](https://docs.livekit.io/telephony/)
>
> LiveKit의 전화 문서예요.

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


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