# Retell AI 연동 (/docs/sip-trunk/retell)

## 개요

한국AI통신 070 번호를 Retell AI 의 SIP 트렁크로 씁니다. 두 방향을 모두 연결할 수 있습니다.

| 방향 | 흐름 |
| --- | --- |
| 걸기 | Retell 에이전트 → 한국AI통신 (SIP Digest 인증) → 받는 사람 |
| 받기 | 거는 사람 → 한국AI통신 070 번호 → Retell SIP 서버 (`sip.retellai.com`) → Retell 에이전트 |

**SIP 트렁크 연결 부가서비스** 가 활성화되어 있어야 합니다.
[대시보드 → 부가서비스](https://platform.claw-ops.com/addons) 에서 켜주세요.

## 동작 흐름

```mermaid
sequenceDiagram
  autonumber
  participant Re as Retell
  participant Co as 한국AI통신
  participant P as 상대방
  Note over Re,P: 걸기
  Re->>Co: SIP INVITE over TLS (From: 07012345678, Digest 인증)
  Co->>P: 발신
  Note over Re,P: 받기
  P->>Co: 070 번호로 발신
  Co->>Re: SIP INVITE over TLS (To: 07012345678)
  Re-->>P: Retell 에이전트가 응답
```

## 사전 준비물

| 항목 | 출처 |
| --- | --- |
| **Retell 계정 + Agent** | [retellai.com](https://www.retellai.com) 대시보드에서 에이전트 생성 |
| **한국AI통신 070 번호** | [대시보드 → 번호](https://platform.claw-ops.com/phone-numbers) |

---

## 1단계 — 한국AI통신에서 SIP 자격증명 발급

[대시보드 → 전화번호 › SIP 단말](https://platform.claw-ops.com/phone-numbers/sip) 에서 **+ Credential 추가** 를 누릅니다.

| 필드 | 값 |
| --- | --- |
| NAME | `Retell` (자유) |
| USERNAME | 영문·숫자·`_`·`-` (예: `retell_01`) |
| ALLOWED NUMBERS | Retell 에 연결할 070 번호 (예: `07012345678`) |

**발급** 을 누르면 비밀번호가 자동으로 만들어집니다. 발급 완료 창의 `auth_id`·`password` 를 2단계에서 씁니다. 비밀번호는 이 창에서만 볼 수 있으니 닫기 전에 복사해 두세요.

---

## 2단계 — Retell 에 번호 가져오기

Retell 대시보드 → **Phone Numbers** → **+** → **Connect to your number via SIP trunking**

| 필드 | 값 |
| --- | --- |
| Phone Number | 오른쪽 형식 선택을 **Keep raw input** 으로 바꾸고 **국내 형식** 입력 — 예: `07012345678` |
| Termination URI | `<계정 ID 소문자>.sip.claw-ops.com` (예: `ac1a2b3c4d.sip.claw-ops.com`) |
| SIP Trunk User Name | 1단계 `auth_id` |
| SIP Trunk Password | 1단계 `password` |
| Additional settings → Outbound Transport | **TLS** (기본값은 TCP) |

**Test SIP Connection** 으로 「SIP connection successful」을 확인한 뒤 **Save** 를 누릅니다. 저장한 번호를 열어 **Inbound Call Agent**·**Outbound Call Agent** 에 에이전트를 지정합니다.

**번호는 국내 형식으로 가져와야 합니다.** 형식 선택의 기본값 **Format to E.164** 를 그대로 두거나 `+827012345678` 로 가져오면 Retell 이 From 을 `+82` 형식으로 보내고, 한국AI통신이 `403` 으로 거절합니다. Retell 에서는 `telephony_provider_permission_denied` 로 표시됩니다.

---

## 3단계 — 전화 걸기

Retell 에서 가져온 번호로 전화를 겁니다. `from_number` 에는 가져온 번호를 국내 형식 그대로 넣고, `to_number` 는 국내 형식과 `+82` 형식 모두 쓸 수 있습니다.

```bash
curl -X POST https://api.retellai.com/v2/create-phone-call \
  -H "Authorization: Bearer $RETELL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "07012345678",
    "to_number": "+821098765432"
  }'
```

---

## 4단계 — 전화 받기

[platform.claw-ops.com/phone-numbers/sip-endpoints](https://platform.claw-ops.com/phone-numbers/sip-endpoints) → **엔드포인트 추가**

| 필드 | 값 |
| --- | --- |
| 엔드포인트 이름 | `Retell` (자유) |
| **User** | 비워 두기 |
| Host | `sip.retellai.com` |
| Port | `5061` |
| Transport | **TLS** |

User 를 비우면 수신 번호가 국내 형식(`07012345678`)으로 들어가, 2단계에서 가져온 번호와 맞습니다.

그다음 번호의 **인바운드 라우팅** 을 **SIP** 로 바꾸고 위 엔드포인트를 선택합니다. 이 번호로 걸려 온 전화는 2단계에서 지정한 에이전트가 받습니다.

---

## 통화 ID 연결

한국AI통신이 Retell 로 보내는 INVITE 의 `X-ClawOps-CallId`·`X-ClawOps-To` 헤더는 Retell 통화의 동적 변수 `clawops-callid`·`clawops-to` 로 들어갑니다. `clawops-callid` 는 한국AI통신 통화 기록·[상태 콜백](/docs/webhooks/status)의 `CallId` 와 같은 값입니다.

## 문제 해결

| 증상 | 원인 / 확인 |
| --- | --- |
| Retell 에 `telephony_provider_permission_denied` | 번호가 `+82` 형식으로 저장됨(Format to E.164), 또는 1단계 ALLOWED NUMBERS 에 그 번호가 없음 |
| 걸기가 연결되지 않고 Retell 에 응답이 없음 | Outbound Transport 가 TLS 인지(기본값 TCP 는 연결되지 않음), Termination URI 가 계정 도메인인지 확인 |
| 받기에서 Retell 이 통화를 받지 않음 | 엔드포인트의 User 가 비어 있는지, Transport 가 TLS 인지 확인 |

## 참고

- [Custom Telephony](https://docs.retellai.com/deploy/custom-telephony) — Retell 공식 가이드
- [PBX에서 전화 걸기](/docs/sip-trunk#pbx에서-전화-걸기) — 같은 방식의 SIP 발신 설정 값