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

# Grok 연동

> xAI Speech to Speech API의 SIP를 거쳐 Telkit 070 번호로 걸려 온 전화를 Grok 음성 에이전트가 받는 방법을 단계별로 안내해요.

xAI Speech to Speech API의 SIP를 거쳐 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)에 있어요. |
| xAI API 키 | 번호를 등록하고 통화에 붙을 때 써요. |
| 웹훅 서버 | xAI가 전화 알림을 보낼 공개 URL이 있는 내 서버예요. |

## 수신

Telkit 번호로 걸려 온 전화를 Grok 음성 에이전트가 받아요. 전화가 올 때마다 xAI가 내 웹훅 서버에 알림을 보내고, 서버가 WebSocket으로 그 통화에 붙어요.

### xAI에 070 번호를 등록해요

`POST https://api.x.ai/v2/phone-numbers`로 내 070 번호를 등록해요. xAI는 이 번호로 오는 전화를 IP allowlist나 digest 인증 가운데 하나로 받는데, Telkit은 아이디와 비밀번호를 보내지 못하니 IP allowlist를 써요. 자세한 칸은 [xAI SIP 문서](https://docs.x.ai/developers/model-capabilities/audio/speech-to-speech/sip)를 봐요.

| xAI 칸 | 넣을 값 |
| - | - |
| `origin` | `byo_trunk` |
| `phone_number` | Telkit 070 번호를 `+827012345678` 모양으로 넣어요. |
| `webhook.url` | 내 웹훅 서버의 공개 URL |
| `sip_auth.allowed_addresses` | 아래 「Telkit이 보내는 전화」 표의 IP 두 개를 `/32`를 붙여 넣어요. |

**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.x.ai/v2/phone-numbers" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "byo_trunk",
    "name": "Telkit 070",
    "phone_number": "+827012345678",
    "webhook": { "name": "Telkit 070", "url": "https://example.com/xai/sip-webhook" },
    "sip_auth": { "allowed_addresses": ["<보내는 IP 1>/32", "<보내는 IP 2>/32"] }
  }'
```

응답의 `webhook.dispatch_signing_secret`이 웹훅 서명 비밀값이에요. 한 번만 보이니 웹훅 서버에 저장해 두세요.

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

xAI는 `sip:{번호}@sip.voice.x.ai`로 전화를 받아요. Telkit 번호 연결에 사용자 없이 `sip:sip.voice.x.ai`를 넣고 번호 형식을 E.164로 하면, Telkit이 받은 070 번호를 `+827012345678` 모양으로 앞에 붙여 보내요. 전송은 기본값인 TLS 그대로 둬요.

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

### 웹훅 서버에서 통화에 붙어요

전화가 오면 xAI가 웹훅으로 `realtime.call.incoming` 알림을 보내요. 서버는 `webhook-id`, `webhook-timestamp`, `webhook-signature` 헤더를 1단계의 서명 비밀값으로 검증하고 `data.call_id`를 읽어요. 그다음 xAI API 키로 `wss://api.x.ai/v1/realtime?call_id={call_id}`에 붙어 `session.update`로 음성 에이전트를 설정하고, 말을 시작할 때 `response.create`를 보내요.

```python Python theme={null}
import json
import os

import websockets


async def handle_sip_call(call_id: str):
    async with websockets.connect(
        f"wss://api.x.ai/v1/realtime?call_id={call_id}",
        additional_headers={"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"},
    ) as ws:
        await ws.send(json.dumps({
            "type": "session.update",
            "session": {
                "voice": "eve",
                "instructions": "전화를 받으면 인사하고 용건을 물어보세요.",
                "turn_detection": {"type": "server_vad"},
            },
        }))
        await ws.send(json.dumps({"type": "response.create"}))

        async for message in ws:
            print(json.loads(message)["type"])
```

붙은 뒤에는 다른 Speech to Speech API 세션과 같아요. 통화 돌려주기와 끊기는 [xAI SIP 문서](https://docs.x.ai/developers/model-capabilities/audio/speech-to-speech/sip)를 봐요.

### 시험 통화를 걸어요

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

## 발신: 지원 안 함

xAI 문서는 Grok 음성 에이전트가 SIP 트렁크로 전화를 거는 방법을 안내하지 않아요. 그래서 Telkit 070 번호로 전화를 걸 수 없어요. 발신이 되는 플랫폼은 [지원 플랫폼](https://telkit.io/docs/connect/platforms.md)에서 확인해요.

## 문제 해결

| 증상 | 할 일 |
| - | - |
| 수신 전화가 바로 끊겨요 | 주소를 저장하고 1분이 지났는지 봐요. xAI에 등록한 번호가 `+82`로 시작하는지, Telkit 번호 연결의 번호 형식이 E.164인지 봐요. |
| xAI가 전화를 받지 않아요 | `sip_auth.allowed_addresses`에 Telkit IP 두 개가 모두 들어 있는지 봐요. 그래도 안 되면 번호 연결의 `srtp`를 `none`으로 해 주세요. xAI 문서에는 음성 암호화 안내가 없어요. |
| 웹훅 알림이 오지 않아요 | 번호를 등록할 때 넣은 `webhook.url`이 밖에서 열리는 주소인지 봐요. |
| 통화가 막혀요 | [한도와 동시 통화](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] [xAI SIP 문서](https://docs.x.ai/developers/model-capabilities/audio/speech-to-speech/sip)
>
> xAI의 SIP 전화 문서예요.

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


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