# SIP 트렁크 (/docs/sip-trunk)

## 개요

한국AI통신 SIP 트렁킹은 070 번호 인바운드를 **외부 SIP URI 로 직접 전달** 할 수 있습니다. AI 음성 SaaS 가 자체 SIP 게이트웨이를 제공하면 한국AI통신이 받은 통화를 그 SIP URI 로 연결합니다. 통화가 이어지는 동안 음성(RTP)은 한국AI통신을 거쳐 오가므로, 받는 쪽 방화벽에는 한국AI통신 시그널링·미디어 IP 를 허용해야 합니다([네트워크 (IP 허용목록)](/docs/network)).

**부가서비스 활성화 필요.** SIP 트렁크 라우팅은 **SIP 트렁크 연결 부가서비스** 입니다.
[대시보드 → 부가서비스](https://platform.claw-ops.com/addons) 에서 활성화 후 진행하세요.

## 아키텍처

```mermaid
flowchart LR
  CALLER([발신자]) -->|PSTN| CARRIER[통신사 게이트웨이]
  CARRIER -->|SIP| CO[한국AI통신]
  CO -->|SIP-over-TLS| SaaS[외부 AI 음성 SaaS]
  SaaS -.->|Webhook<br/>realtime.call.incoming| YOUR[고객사 webhook 서버]
  YOUR -.->|accept + WS| SaaS
```

## 지원 패턴

| Provider | 라우팅 URI | 인증 |
| --- | --- | --- |
| **OpenAI Realtime** | `sip:proj_xxx@sip.api.openai.com:5061;transport=tls` | project_id + webhook |
| **ElevenLabs Agents** | `sip:+8270xxxxxxxx@sip.rtc.elevenlabs.io:5061;transport=tls` | 번호 import + agent 할당 (digest 선택) |
| **Retell AI** | `sip:sip.retellai.com:5061;transport=tls` | 번호 import(국내 형식) + 걸기는 SIP Digest |

## 공통 설정 흐름

1. **대시보드 → 번호** 에서 사용할 070 번호 선택
2. **부가서비스 활성화** ([대시보드 → 부가서비스](https://platform.claw-ops.com/addons) → SIP 트렁크 연결)
3. **[SIP 엔드포인트 등록](https://platform.claw-ops.com/phone-numbers/sip-endpoints)** — 외부 SaaS 도착지 URI 입력
4. **번호의 인바운드 라우팅을 SIP 로 전환** + 위에서 만든 엔드포인트 선택
5. **(provider 측)** webhook / agent / assistant 등록

**방화벽/PBX 화이트리스트** — 사내 PBX·FreeSWITCH·Asterisk 등 자체 SIP 게이트웨이를 IP 허용목록으로 운영하신다면,
저희 SIP 시그널링·RTP 미디어 고정 IP를 함께 허용해 주세요. 전체 목록은 [네트워크 (IP 허용목록)](/docs/network) 을 참고하세요.

## 요금

SIP 트렁크 연결 부가서비스는 월 ₩99,000이고 체험 기간에는 무료입니다. 체험·Individual 이상 플랜에서 켤 수 있습니다. 통화 요금은 [요금](/docs/api-reference/pricing)의 플랜 단가를 따릅니다.

## PBX에서 전화 걸기

사내 PBX·Asterisk·FreeSWITCH 에서 한국AI통신 070 번호로 전화를 걸 수 있습니다. 콘솔 **전화번호 › SIP 단말**에서 SIP 자격증명을 만든 뒤 아래 값으로 INVITE 를 보냅니다.

| 항목 | 값 |
| --- | --- |
| 접속 주소 | `<계정 ID 소문자>.sip.claw-ops.com` |
| Transport | TLS, 포트 5061 |
| 인증 | SIP Digest(자격증명의 username·password). 등록(REGISTER) 없이 INVITE 만 보내도 됩니다 |
| From | 계정이 보유한 번호를 국내 형식(`07012345678`)으로 넣습니다 |
| 받는 번호 | 국내 형식(`01012345678`) 또는 `+82` 형식 |
| DTMF | RFC 4733(RFC 2833). SIP INFO 는 지원하지 않습니다 |

- 계정이 보유하지 않은 번호나 `+82` 형식을 From 에 넣으면 `403` 으로 거절됩니다.
- 자격증명에 허용 번호를 지정했다면 그 번호만 From 에 쓸 수 있습니다.

## INVITE 에 실리는 값

한국AI통신이 SIP 엔드포인트로 보내는 INVITE 에서 아래 값을 읽을 수 있습니다.

| 값 | 어디에 | 설명 |
| --- | --- | --- |
| 발신자 번호 | `From` | 통신사가 보내 준 발신자 번호를 형식 그대로 싣습니다(국내 휴대폰은 `01012345678` 형식). 발신자가 번호 표시를 제한하고 건 통화는 번호 대신 `anonymous` 를 싣습니다. |
| 걸려온 번호 | `X-ClawOps-To` | 이 SIP 트렁크로 연결된 한국AI통신 번호입니다(착신전환을 거쳐 들어왔다면 최종으로 도착한 번호). 등록한 URI 와 관계없이 실립니다. |
| 걸려온 번호 | Request-URI · `To` 의 user 부분 | 등록한 URI 에 user 부분이 **없을 때만**(`sip:pbx.example.com`) 070 번호가 들어갑니다. user 부분이 있으면(`sip:frontdesk@pbx.example.com`) 입력하신 URI 그대로 보냅니다. |
| 통화 ID | `X-ClawOps-CallId` | 한국AI통신 통화 ID(`CA…`)입니다. [상태 콜백](/docs/webhooks/status)의 `CallId`, 통화 기록 조회의 통화 ID 와 **같은 값**이라 INVITE 와 상태 콜백을 한 통화로 묶을 때 씁니다. |

```
INVITE sip:07012345678@pbx.example.com SIP/2.0
From: <sip:01012345678@...>;tag=...
To: <sip:07012345678@pbx.example.com>
X-ClawOps-CallId: CA0123456789abcdef0123456789abcdef
X-ClawOps-To: 07012345678
```

한국AI통신이 SIP 엔드포인트로 보내는 통화의 코덱은 PCMU·PCMA 이고, DTMF 는 RFC 4733(RFC 2833)입니다.

헤더 이름은 대소문자를 구분하지 않고 읽어 주세요(SIP 규약). 앞으로 `X-ClawOps-` 로 시작하는 헤더가 늘어날 수 있으니, 모르는 헤더는 무시하도록 처리해 주세요.

## 음성 암호화 (SRTP)

한국AI통신과 SIP 서버 사이의 음성(RTP)을 SRTP 로 암호화할 수 있습니다. 키 교환은 SDES(SDP `a=crypto`, RFC 4568) 입니다.

| 방향 | 설정 |
| --- | --- |
| 한국AI통신 → SIP 엔드포인트 (착신 전달) | [SIP 라우팅](https://platform.claw-ops.com/phone-numbers/sip-endpoints)의 라우트에서 **음성 암호화 (SRTP)** 스위치를 켭니다. API 는 라우트의 `mediaCrypto` 를 `sdes` 로 저장합니다. |
| SIP 서버 → 한국AI통신 (발신) | SIP 서버가 `RTP/SAVP` 와 `a=crypto` 로 제안하면 한국AI통신이 SRTP 로 받습니다. 별도 설정은 없습니다. |

- 음성 암호화는 전송 방식이 TLS 인 라우트에서만 켤 수 있습니다.
- 착신 전달에서 제안하는 crypto suite 는 `AES_CM_128_HMAC_SHA1_80`, `AES_CM_128_HMAC_SHA1_32` 입니다.
- 음성 암호화를 켠 라우트는 받는 SIP 서버가 SRTP 로 응답하지 않으면 연결되지 않고 다음 라우트로 넘어갑니다. 다음 라우트의 음성 암호화가 꺼져 있으면 그 통화는 평문으로 연결됩니다.
- 음성 암호화를 켠 라우트의 SIP 서버는 공용 CA 가 발급한 TLS 인증서를 써야 합니다.
- 받는 SIP 서버가 SRTP 를 필수로 요구하면(예: LiveKit `media_encryption` REQUIRE) 라우트의 음성 암호화를 켜야 합니다.
- 외부 SIP 인증을 쓰는 엔드포인트와 한국AI통신 SIP 도메인 라우트는 음성 암호화를 지원하지 않습니다.
- 암호화 구간은 한국AI통신과 SIP 서버 사이입니다. 전화망(PSTN) 구간은 포함하지 않습니다.

## 가이드

- [OpenAI Realtime](/docs/sip-trunk/openai-realtime) — 실시간 음성 모델 (gpt-realtime) 연동, webhook 핸들러 코드 포함
- [ElevenLabs Agents](/docs/sip-trunk/elevenlabs) — ElevenLabs Conversational AI 에이전트 연동, 번호 import 가이드 포함
- [Retell AI](/docs/sip-trunk/retell) — Retell 에이전트로 걸기·받기 양방향 연동