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

# OpenAI 연동

> OpenAI의 SIP를 거쳐 Telkit 070 번호로 걸려 온 전화를 GPT-Live 음성 에이전트가 받는 방법을 단계별로 안내해요.

OpenAI의 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)에 있어요. |
| OpenAI 프로젝트 | GPT-Live SIP 사용이 켜진 프로젝트예요. |
| OpenAI API 키 | 같은 프로젝트의 키예요. 웹훅 서버가 전화를 받을 때 써요. |
| 웹훅 서버 | OpenAI가 전화 알림을 보낼 공개 URL이 있는 내 서버예요. |

## 수신

Telkit 번호로 걸려 온 전화를 GPT-Live 음성 에이전트가 받아요. 전화가 올 때마다 OpenAI가 내 웹훅 서버에 알림을 보내고, 서버가 `accept`를 보내야 통화가 시작돼요.

### OpenAI에서 웹훅을 만들어요

[OpenAI settings](https://platform.openai.com/settings)에서 프로젝트를 열고 **Webhooks**에서 **Create**를 눌러 아래처럼 채워요. 자세한 칸은 [OpenAI 웹훅 문서](https://developers.openai.com/api/docs/guides/webhooks)를 봐요.

| OpenAI 칸 | 넣을 값 |
| - | - |
| **Name** | 알아볼 이름이에요. 아무 이름이나 돼요. |
| **URL** | 내 웹훅 서버의 공개 URL |
| **Event types** | `live.transport.incoming` |

만들면 서명 비밀값이 한 번만 보여요. 웹훅 서버의 환경 변수 `OPENAI_WEBHOOK_SECRET`에 넣어 두세요.

같은 프로젝트의 **General**에서 프로젝트 ID를 확인해요. `proj_`로 시작해요.

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

SIP 주소는 `sip:{프로젝트 ID}@sip.api.openai.com`이에요. 유럽에 데이터를 두는 프로젝트는 `sip-eu.api.openai.com`을 써요. 아래 `proj_abc123`을 1단계에서 확인한 프로젝트 ID로 바꿔요.

> [tab] 에이전트
>
> Telkit 070 번호로 걸려 온 전화를 OpenAI 프로젝트의 SIP 주소로 넘기는 한 줄이에요.
>
> [https://telkit.io/llms.txt](https://telkit.io/llms.txt) 를 읽고 내 070 번호로 걸려 온 전화가 sip:[proj\_abc123@sip.api.openai.com](mailto:proj_abc123@sip.api.openai.com) 으로 가게 해 줘.

> [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:proj_abc123@sip.api.openai.com"}'
> ```
>
> 응답의 `updated_at`에서 1분이 지나면 새 주소로 전화가 가요.

전송, 음성 암호화, 번호 형식은 기본값 그대로 둬요. OpenAI는 TLS 신호와 SRTP 음성을 요구하고, Telkit 기본값이 TLS와 SDES SRTP예요.

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

### 웹훅 서버에서 전화를 받아요

전화가 오면 OpenAI가 웹훅으로 `live.transport.incoming` 알림을 보내요. 서버는 서명을 검증하고, `data.type`이 `sip`이면 `data.session_id`를 그대로 써서 `POST /v1/live/sessions/{session_id}/accept`를 보내요. `200`이 오면 통화가 시작돼요. 같은 알림이 다시 올 수 있으니 `webhook-id` 헤더로 한 번만 처리해 주세요.

```js Node.js theme={null}
import express from "express";
import OpenAI from "openai";

const openai = new OpenAI({ webhookSecret: process.env.OPENAI_WEBHOOK_SECRET });
const app = express();

// 서명 검증에는 가공하지 않은 본문이 필요해서 글자 그대로 받아요.
app.post("/openai/webhook", express.text({ type: "application/json" }), async (req, res) => {
  const event = await openai.webhooks.unwrap(req.body, req.headers).catch(() => null);
  if (!event) return res.status(400).send("invalid signature");

  if (event.type === "live.transport.incoming" && event.data.type === "sip") {
    const accepted = await fetch(
      `https://api.openai.com/v1/live/sessions/${event.data.session_id}/accept`,
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          session: {
            type: "live",
            model: "gpt-live-1",
            instructions: "전화를 받으면 인사하고 용건을 물어보세요.",
            audio: { output: { voice: "marin" } },
          },
        }),
      },
    );
    // 5xx로 답하면 OpenAI가 같은 알림을 다시 보내요.
    if (!accepted.ok) return res.sendStatus(502);
  }
  res.sendStatus(200);
});

app.listen(8000);
```

`accept` 본문에 `audio.format`은 넣지 않아요. 음성 형식은 SIP가 정해요. 받지 않을 전화는 `POST /v1/live/sessions/{session_id}/reject`에 `{"status_code": 486}`처럼 300 \~ 699 사이의 SIP 응답 코드를 보내요. 도구와 통화 중 이벤트는 [OpenAI SIP 문서](https://developers.openai.com/api/docs/guides/voice-sip)를 봐요.

### 시험 통화를 걸어요

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

## 발신: 지원 안 함

OpenAI API 레퍼런스는 SIP 트렁크에 Opus를 요구하고 Telkit 발신은 G.711만 받아요. 그래서 OpenAI 음성 에이전트가 Telkit 070 번호로 전화를 걸 수 없어요. 발신이 되는 플랫폼은 [지원 플랫폼](https://telkit.io/docs/connect/platforms.md)에서 확인해요.

## 문제 해결

| 증상 | 할 일 |
| - | - |
| 수신 전화가 바로 끊겨요 | 주소를 저장하고 1분이 지났는지 봐요. 주소의 프로젝트 ID가 웹훅을 만든 프로젝트의 ID와 같은지 봐요. |
| 웹훅 알림이 오지 않아요 | 프로젝트에서 GPT-Live SIP 사용이 켜져 있는지, 웹훅의 **Event types**에 `live.transport.incoming`이 있는지 봐요. |
| 알림은 오는데 통화가 시작되지 않아요 | 서버가 `accept`를 보냈는지, 응답이 `200`인지 봐요. `accept`를 보내지 않으면 전화가 연결되지 않아요. |
| 서명 검증이 실패해요 | `OPENAI_WEBHOOK_SECRET`이 이 웹훅을 만들 때 받은 값인지, 본문을 가공하지 않고 검증하는지 봐요. |
| 통화가 막혀요 | [한도와 동시 통화](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] [OpenAI SIP 문서](https://developers.openai.com/api/docs/guides/voice-sip)
>
> OpenAI의 전화와 SIP 문서예요.

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


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