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

# Pipecat 연동

> Daily SIP Trunk를 거쳐 Telkit 070 번호로 걸려 온 전화를 Pipecat 음성 에이전트가 받는 방법을 단계별로 안내해요.

Daily SIP Trunk를 거쳐 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)에 있어요. |
| Daily 유료 계정과 API 키 | Daily SIP Trunk는 유료 계정에서만 만들 수 있어요. |
| 웹훅 서버 | Daily가 전화 알림을 보낼 공개 HTTPS 주소가 있는 내 서버예요. |
| Pipecat 음성 에이전트 | Daily 방에 들어가 전화를 받는 Pipecat 봇이에요. |

## 수신

Telkit 번호로 걸려 온 전화를 Pipecat 음성 에이전트가 받아요. 전화가 오면 Daily가 방을 하나 만들고 내 웹훅 서버에 알림을 보내요. 서버가 답하고 음성 에이전트를 그 방에 들여보내면 Daily가 건 사람을 방에 이어요.

### 웹훅 서버를 먼저 열어요

Daily는 트렁크를 만들 때 웹훅 주소로 `sip_trunk.test` 요청을 보내고, 2xx로 답하지 않으면 트렁크를 만들지 않아요. 그래서 트렁크보다 웹훅 서버를 먼저 열어요.

전화가 오면 Daily가 `sip_trunk.incoming` 알림을 보내요. 서버는 아래 순서로 처리해요. 서명 확인과 자세한 내용은 [Daily SIP Trunk 문서](https://docs.daily.co/docs/guides/features/dial-in-dial-out/sip-trunk)의 Connect your bot을 봐요.

| 순서 | 할 일 |
| - | - |
| 1 | 2xx로 바로 답해요. 약 12초 안에 답하지 않으면 Daily가 전화를 `480`으로 거절해요. |
| 2 | 알림의 `room.url`로 Pipecat 음성 에이전트를 띄워요. Pipecat 봇은 `DailyTransport`에 방 주소를 넣어 들어가요. 방법은 [Pipecat Daily SIP 문서](https://docs.pipecat.ai/pipecat/telephony/daily-sip)의 Bot configuration을 봐요. |
| 3 | 건 사람이 방에 들어오면 말을 시작해요. |

### Daily SIP Trunk를 만들어요

Daily REST API의 `POST /sip-trunk`로 트렁크를 만들어요. Daily 문서는 이 API로만 트렁크를 만드는 방법을 안내해요. 트렁크는 IP 허용 목록이나 아이디·비밀번호 가운데 하나로 막아 두어야 하는데, Telkit은 아이디와 비밀번호를 보내지 못하니 IP 허용 목록을 써요.

| Daily 칸 | 넣을 값 |
| - | - |
| `trunk_name` | 소문자와 숫자로 된 이름. 하이픈은 쓸 수 없어요. |
| `notification.webhook_url` | 1단계의 웹훅 주소 |
| `trunk_config.allowed_ips` | 아래 「Telkit이 보내는 전화」 표의 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`로 실려요. |

```bash theme={null}
curl -s -X POST "https://api.daily.co/v1/sip-trunk" \
  -H "Authorization: Bearer $DAILY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trunk_name": "telkit",
    "notification": { "webhook_url": "https://example.com/daily/sip-trunk" },
    "trunk_config": { "allowed_ips": ["<보내는 IP 1>", "<보내는 IP 2>"] }
  }'
```

응답의 `sip_uri`가 Telkit 번호를 넘길 주소예요. 응답의 `config.notification.hmac`은 웹훅 서명을 확인하는 비밀값이니 웹훅 서버에 저장해 두세요.

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

Telkit 번호 연결에 응답의 `sip_uri`를 그대로 넣어요. Daily는 주소의 호스트로 트렁크를 찾고 사용자 부분은 보지 않으므로 번호 형식은 기본값 그대로 둬도 돼요. Daily는 TLS를 권하고 Telkit이 SRTP를 제안하면 SDES로 맞추므로 전송과 `srtp`도 기본값인 TLS와 `sdes`로 둬요. 아래 주소는 모양을 보이는 예라 2단계 응답의 `sip_uri`로 바꿔 넣어요.

> [tab] 에이전트
>
> Telkit 070 번호로 걸려 온 전화를 Daily SIP Trunk 주소로 넘기는 한 줄이에요.
>
> [https://telkit.io/llms.txt](https://telkit.io/llms.txt) 를 읽고 내 070 번호로 걸려 온 전화가 sip:examplecorp-telkit.siptrunk.sip-us.daily.co 로 가게 해 줘.

> [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:examplecorp-telkit.siptrunk.sip-us.daily.co"}'
> ```
>
> 응답의 `updated_at`에서 1분이 지나면 새 주소로 전화가 가요.

### 시험 통화를 걸어요

웹훅 서버를 실행하고 내 휴대폰으로 070 번호에 전화를 걸어요. 신호음이 가는 동안 웹훅 서버에 알림이 오고, Pipecat 음성 에이전트가 받으면 끝나요. 주소를 저장하고 1분이 지나기 전에 걸면 끊길 수 있어요.

## 발신: 지원 안 함

이 쪽이 쓰는 Daily SIP Trunk는 수신 전용이라 Telkit 070 번호로 전화를 걸 수 없어요. Daily 문서의 Limitations에 「Inbound termination only」로 적혀 있어요. Pipecat이 Daily dial-out으로 SIP 주소에 거는 방법은 [Pipecat Daily SIP 문서](https://docs.pipecat.ai/pipecat/telephony/daily-sip)에 있지만 이 쪽이 다루는 방식이 아니에요. 발신이 되는 플랫폼은 [지원 플랫폼](https://telkit.io/docs/connect/platforms.md)에서 확인해요.

## 문제 해결

| 증상 | 할 일 |
| - | - |
| 트렁크를 만들 때 `400`이 나요 | 웹훅 서버가 밖에서 열리고 `sip_trunk.test` 요청에 2xx로 답하는지 봐요. |
| 수신 전화가 바로 끊겨요 | 주소를 저장하고 1분이 지났는지 봐요. `trunk_config.allowed_ips`에 Telkit IP 두 개가 모두 들어 있는지, 번호 연결 주소가 응답의 `sip_uri`와 같은지 봐요. |
| 신호음만 가다가 끊겨요 | 웹훅 서버가 약 12초 안에 2xx로 답하는지 봐요. 2xx를 먼저 보내고 음성 에이전트는 그다음에 띄워요. |
| 전화가 `488`로 거절되거나 소리가 나지 않아요 | Daily 트렁크는 기본으로 `PCMU` 하나만 맞춰요. 코덱은 [Daily SIP Trunk 문서](https://docs.daily.co/docs/guides/features/dial-in-dial-out/sip-trunk)의 Codecs를 봐요. |
| 통화가 막혀요 | [한도와 동시 통화](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] [Daily SIP Trunk 문서](https://docs.daily.co/docs/guides/features/dial-in-dial-out/sip-trunk)
>
> Daily의 SIP Trunk 문서예요.

> [card] [Pipecat Daily SIP 문서](https://docs.pipecat.ai/pipecat/telephony/daily-sip)
>
> Pipecat 봇이 Daily 방에 들어가는 방법이에요.

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


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