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

# Gemini 연동

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

LiveKit의 SIP를 거쳐 Telkit 070 번호로 Gemini 음성 에이전트가 전화를 받고 걸어요. 수신과 발신이 모두 돼요. Gemini Live API에는 SIP 연결이 없어서 전화는 LiveKit이 맡고, Gemini는 LiveKit 음성 에이전트의 실시간 모델로 붙어요. LiveKit 쪽 단계는 [LiveKit 연동](https://telkit.io/docs/connect/livekit.md)과 같아요.

## 준비물

| 항목 | 설명 |
| - | - |
| Telkit 070 번호 | 번호 구매는 [첫 통화](https://telkit.io/docs/connect/first-call.md)에서 해요. |
| Telkit API 키 | 「API」 탭을 쓸 때만 필요해요. 받는 방법은 [LiveKit 연동의 준비물](https://telkit.io/docs/connect/livekit.md#prepare)에 있어요. |
| 등록한 카드 | 카드가 없으면 발신 접속 정보를 만들 수 없어요. |
| LiveKit Cloud 프로젝트 | SIP URI는 LiveKit Cloud의 **Project settings**에서 확인해요. `sip:vjnxecm0tjk.sip.livekit.cloud` 모양이에요. |
| Gemini API 키 | 음성 에이전트가 `GOOGLE_API_KEY`로 써요. [Gemini API 키 문서](https://aistudio.google.com/docs/api-key)를 따라 만들어요. |

## 수신

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

### LiveKit 음성 에이전트에 Gemini를 붙여요

LiveKit 음성 에이전트에 Google 플러그인을 설치하고, 음성 에이전트 환경에 `GOOGLE_API_KEY`를 넣어요. 음성 에이전트가 없으면 [LiveKit Voice AI quickstart](https://docs.livekit.io/agents/start/voice-ai/)로 먼저 만들어요.

```shell theme={null}
uv add "livekit-agents[google]~=1.8"
```

`AgentSession`의 `llm`에 Gemini 실시간 모델을 넣어요. 모델과 다른 칸은 [LiveKit Gemini Live API 문서](https://docs.livekit.io/agents/models/realtime/gemini/)를 봐요.

```python theme={null}
from livekit.plugins import google

session = AgentSession(
    llm=google.realtime.RealtimeModel(
        voice="Puck",
        temperature=0.8,
        instructions="You are a helpful assistant",
    ),
)
```

### LiveKit에서 inbound trunk와 dispatch rule을 만들어요

[LiveKit 연동의 inbound trunk 단계](https://telkit.io/docs/connect/livekit.md#inbound-trunk)와 [dispatch rule 단계](https://telkit.io/docs/connect/livekit.md#inbound-dispatch)를 그대로 해요. dispatch rule의 `agent_name`에는 1단계 음성 에이전트의 이름을 넣어요. inbound trunk의 `allowed_addresses`에 넣을 IP는 아래 표에 있어요.

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

### 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분이 지나면 새 주소로 전화가 가요.

### 시험 통화를 걸어요

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

## 발신

Gemini 음성 에이전트가 Telkit 070 번호로 전화를 걸어요. 음성 에이전트는 [수신 1단계](#gemini-agent)에서 만든 것을 써요.

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

> [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 연동의 outbound trunk 단계](https://telkit.io/docs/connect/livekit.md#outbound-trunk)를 그대로 해요. `auth_username`과 `auth_password`에는 위 표의 에이전트가 건네준 값을 넣어요.

### 시험 통화를 걸어요

비밀번호를 만들고 1 \~ 2분 뒤에 Gemini 음성 에이전트가 `CreateSIPParticipant`로 내 휴대폰에 전화를 걸게 해요. 넣을 값은 [LiveKit 연동의 발신 시험 통화](https://telkit.io/docs/connect/livekit.md#outbound-test)와 같아요. 휴대폰에 내 070 번호가 뜨고 음성 에이전트가 말하면 끝나요.

## 문제 해결

| 증상 | 할 일 |
| - | - |
| 전화는 이어지는데 음성 에이전트가 말하지 않아요 | 음성 에이전트 환경에 `GOOGLE_API_KEY`가 있는지, Google 플러그인이 설치됐는지 봐요. |
| 수신이나 발신이 연결되지 않아요 | [LiveKit 연동의 문제 해결](https://telkit.io/docs/connect/livekit.md#troubleshooting)을 봐요. 전화는 LiveKit 설정을 따라요. |
| 통화가 막혀요 | [한도와 동시 통화](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] [Gemini Live API 문서](https://aistudio.google.com/docs/live-api)
>
> Gemini의 실시간 음성 문서예요.

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


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