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

# Vapi 연동

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

Vapi의 BYO 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)에 있어요. |
| 등록한 카드 | 카드가 없으면 발신 접속 정보를 만들 수 없어요. |
| Vapi private API 키 | SIP trunk credential은 Vapi API로 만들어요. |
| Vapi assistant | 전화를 받고 걸 음성 에이전트예요. |

Vapi 조직이 EU 리전이면 아래 Vapi API 주소는 `https://api.eu.vapi.ai`, SIP 주소는 `sip.eu.vapi.ai`를 써요. US 리전은 `https://api.vapi.ai`와 `sip.vapi.ai`예요.

## 수신

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

### Vapi에서 SIP trunk credential을 만들어요

Vapi API의 `POST /credential`로 `provider`가 `byo-sip-trunk`인 credential을 만들어요. Vapi는 들어온 전화의 출발 IP를 숫자 IPv4로 맞춰 보므로 수신 gateway에는 주소 이름이 아니라 IP를 넣어요. 자세한 칸은 [Vapi SIP trunk 문서](https://docs.vapi.ai/advanced/sip/sip-trunk)와 [gateway 칸 설명](https://docs.vapi.ai/advanced/sip/troubleshoot-sip-trunk-credential-errors#gateway-configuration-reference)을 봐요.

| Vapi 칸 | 넣을 값 |
| - | - |
| `provider` | `byo-sip-trunk` |
| `gateways` | 아래 「Telkit이 보내는 전화」 표의 IP 두 개를 gateway 하나씩으로 넣어요. |
| `gateways[].netmask` | `32` |
| `gateways[].port` | `5061` |
| `gateways[].inboundEnabled` | `true` |
| `gateways[].outboundEnabled` | `false`. 발신 gateway는 「발신」에서 더해요. |

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

Vapi 대시보드에서는 **Integrations**의 **Phone Number Providers**에서 **SIP Trunk**를 고르고 **Configure New SIP Trunk**를 눌러 같은 값을 넣어요. gateway마다 **Allow inbound calls**를 켜고 **Allow outbound calls**를 꺼요.

응답의 `id`가 credential ID예요. 다음 단계와 수신 주소에 써요.

> [!NOTE]
>
> Vapi 문서는 서버를 여러 고객이 함께 쓰기 때문에 IP 인증을 권하지 않아요. Vapi는 수신 전화를 출발 IP로만 맞춰 보고 Telkit은 아이디와 비밀번호를 보내지 못해서, 수신에는 이 방법을 써요.

### Telkit 번호를 Vapi로 가져와요

Vapi 대시보드의 **Phone Numbers**에서 **Create Phone Number**를 누르고 **BYO SIP Trunk Number**를 골라요. API로는 `POST /phone-number`예요. 자세한 칸은 [Vapi 번호 가져오기 예](https://docs.vapi.ai/phone-numbers/didww)를 봐요.

| Vapi 칸 | 넣을 값 |
| - | - |
| `provider` | `byo-phone-number` |
| `number` | Telkit 070 번호를 `+827012345678` 모양으로 넣어요. |
| `numberE164CheckEnabled` | `true`. 대시보드에서는 **Allow non-E164 phone numbers**를 꺼 둬요. |
| `credentialId` | 1단계의 credential ID |
| `assistantId` | 전화를 받을 assistant. 대시보드에서는 가져온 번호를 열어 **Inbound Settings**에서 골라요. |

응답의 `id`가 Vapi 번호 ID예요. 발신 시험 통화에 써요.

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

Vapi는 `{번호}@CREDENTIAL_ID.sip.vapi.ai`로 전화를 받아요. Telkit 번호 연결에 사용자 없이 `sip:CREDENTIAL_ID.sip.vapi.ai`를 넣고 번호 형식을 E.164로 하면, Telkit이 받은 070 번호를 `+827012345678` 모양으로 앞에 붙여 보내요. `CREDENTIAL_ID`는 1단계의 credential ID로 바꿔요.

전송은 TLS로 하고 `srtp`는 `none`으로 해요. Vapi 문서는 수신 전화의 음성 암호화를 안내하지 않아요.

> [tab] 에이전트
>
> Telkit 070 번호로 걸려 온 전화를 Vapi SIP 주소로 넘기는 한 줄이에요.
>
> [https://telkit.io/llms.txt](https://telkit.io/llms.txt) 를 읽고 내 070 번호로 걸려 온 전화가 sip:CREDENTIAL\_ID.sip.vapi.ai 로 가게 해 줘. 전송은 TLS, srtp는 none, 번호 형식은 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:CREDENTIAL_ID.sip.vapi.ai","transport":"tls","srtp":"none","number_format":"e164"}'
> ```
>
> 응답의 `updated_at`에서 1분이 지나면 새 주소로 전화가 가요.

### 시험 통화를 걸어요

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

## 발신

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

### Vapi credential에 발신 gateway를 더해요

수신에서 만든 credential에 발신 gateway 하나와 인증 정보를 더해요. Vapi는 이미 있는 credential을 고칠 때 `PATCH /credential/CREDENTIAL_ID`로 `gateways` 배열 전체를 보내라고 안내해요. 수신 gateway 두 개를 그대로 두고 아래 gateway를 더해 보내요. 자세한 방법은 [Vapi Twilio SIP 문서](https://docs.vapi.ai/advanced/sip/twilio)의 credential 단계를 봐요.

| Vapi 칸 | 넣을 값 |
| - | - |
| `gateways[].ip` | `sip.telkit.io`. 발신 gateway에는 주소 이름을 쓸 수 있어요. |
| `gateways[].port` | `5061` |
| `gateways[].outboundProtocol` | `tls/srtp`. 음성 암호화 없이 쓰려면 `tls` |
| `gateways[].inboundEnabled` | `false` |
| `gateways[].outboundEnabled` | `true` |
| `outboundAuthenticationPlan.authUsername`, `outboundAuthenticationPlan.authPassword` | 에이전트가 건네준 값 |

### 시험 통화를 걸어요

비밀번호를 만들고 1 \~ 2분 뒤에 Vapi에서 내 휴대폰으로 전화를 걸어요. 대시보드에서 가져온 번호와 assistant를 고르고 받는 번호를 넣거나, `POST /call/phone`에 `assistantId`, `phoneNumberId`, `customer.number`를 보내요. 받는 번호는 `+821012345678` 모양으로 넣어요. 휴대폰에 내 070 번호가 뜨고 음성 에이전트가 말하면 끝나요. 방법은 [Vapi 발신 문서](https://docs.vapi.ai/calls/outbound-calling)를 봐요.

## 문제 해결

| 증상 | 할 일 |
| - | - |
| 수신 전화가 바로 끊겨요 | 주소를 저장하고 1분이 지났는지 봐요. Vapi에 가져온 번호가 `+82`로 시작하는지, Telkit 번호 연결의 번호 형식이 E.164인지 봐요. |
| 수신 전화가 `401`로 거절돼요 | credential의 수신 gateway에 Telkit IP 두 개가 모두 있는지 봐요. Vapi 문서는 IP가 빠지면 `401`이 날 수 있다고 해요. |
| credential을 만들 때 `SIP gateway creation failed`가 나요 | `inboundEnabled`가 `true`인 gateway의 `ip`에 주소 이름 대신 숫자 IP를 넣었는지 봐요. |
| 발신 접속 정보를 만들 수 없어요 | 카드를 등록했는지, 번호의 발신이 열렸는지 에이전트에게 확인해 달라고 해요. 카드가 없거나 발신이 열리는 중이면 만들 수 없어요. |
| 발신이 거절돼요 | 비밀번호를 만들고 1 \~ 2분이 지났는지, 발신 gateway의 `port`가 `5061`이고 `outboundProtocol`이 `tls`나 `tls/srtp`인지, 사용자 이름과 비밀번호가 에이전트가 건네준 값과 같은지 봐요. 비밀번호를 잃었으면 에이전트에게 새로 만들어 달라고 해요. |
| 통화가 막혀요 | [한도와 동시 통화](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] [Vapi SIP trunk 문서](https://docs.vapi.ai/advanced/sip/sip-trunk)
>
> Vapi의 SIP trunk 문서예요.

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


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