# 통화 클라이언트 (/docs/clients)

## 통화 클라이언트

한국AI통신 번호는 **PSTN 게이트웨이** 일 뿐 아니라, 클라이언트 단말이 직접 SIP 등록해서 발신/수신할 수 있는 **CPaaS 엔드포인트** 이기도 합니다.

| 클라이언트 | 사용 사례 | 가이드 |
| --- | --- | --- |
| 브라우저 (WebRTC) | "전화하기" 버튼, 브라우저 내장 콜센터, 클릭투콜 데모 | [WebRTC 통합](/docs/clients/webrtc) |
| SIP 소프트폰 (Linphone 등) | 데스크톱/모바일 단말, 데스크폰, 사내 콜센터 | [SIP 단말 (Linphone)](/docs/clients/sip) |

**부가서비스 활성화 필요.** WebRTC / SIP 단말 등록은 기본 플랜에 포함되지 않은 **SIP 트렁크 연결 부가서비스** 입니다. 사용 전에 [대시보드 → 부가서비스](https://platform.claw-ops.com/) 에서 활성화하거나 영업팀에 문의해주세요. 활성화 전에는 SipCredential 생성 / 토큰 발급이 차단됩니다.

두 방식 모두 같은 한국AI통신 SIP 게이트웨이를 공유합니다. 차이는 **시그널링 트랜스포트** 뿐입니다 — WebRTC 는 SIP-over-WSS, SIP 단말은 SIP-over-TLS(5061).

## 공통 인증 모델

한국AI통신 클라이언트 인증은 **2-tier credential** 구조입니다 (Twilio Voice JS / Vonage Client SDK 와 동일 패턴).

```mermaid
flowchart TB
  A["SipCredential (영구)<br/>대시보드에서 1회 발급<br/>realm, allowed_caller_ids 정책 보관<br/>서버 보관 — 클라이언트 노출 X"]
  B["JWT 단기 토큰 (TTL 기본 1시간 · 최대 24시간)<br/>랜덤 sip_username, sip_password 1회용<br/>realm, ws_url, allowed_caller_ids 동봉<br/>SIP digest 인증에 사용"]
  A -->|POST /tokens 서버 to 서버| B
```

**왜 2-tier 인가**

- 영구 credential 을 브라우저/단말에 절대 노출하지 않음
- 토큰 TTL 만료 → 자동 폐기. 도용 영향 최소화
- realm/허용번호 정책은 서버 한 곳에서만 관리

## 발급 흐름

```mermaid
sequenceDiagram
  autonumber
  participant Cl as Client
  participant Sv as Your Server
  participant Co as 한국AI통신 API
  participant Gw as 한국AI통신 SIP gateway
  Cl->>Sv: 통화 시작 요청 (인증, 봇, Rate-limit)
  Sv->>Co: POST /sip-credentials/:id/tokens (Bearer API Key)
  Co-->>Sv: JWT (token, ws_url, realm, ...)
  Sv->>Co: GET /ice-servers
  Co-->>Sv: ice_servers
  Sv-->>Cl: JWT + ICE servers
  Cl->>Gw: SIP REGISTER (digest auth)
  Gw-->>Cl: 200 OK
  Cl->>Gw: INVITE 상대 번호
  Gw-->>Cl: 응답
```

## 보안 권장

| 위험 | 권장 대응 |
| --- | --- |
| API Key 유출 | 토큰 발급은 **반드시 서버측에서**. 절대 클라이언트에 API Key 내장 금지 |
| 봇/스팸 발신 | Cloudflare Turnstile / reCAPTCHA / 로그인 필수화 |
| 비용 폭주 | 토큰 발급 Rate-limit (계정당 시간/일 제한) + 통화 자체에 max-duration cap |
| 토큰 도용 | 짧은 TTL(7~30분) + 통화 1건당 토큰 1개 |

## 다음 페이지

- [WebRTC 통합](/docs/clients/webrtc) — 브라우저에서 click-to-call. JsSIP + 토큰 발급 API + ICE 설정 전체 예제
- [SIP 단말 (Linphone)](/docs/clients/sip) — Linphone 등 SIP 소프트폰 등록