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

# 통화 결과와 웹훅

> 통화가 왜 끝났는지 통화 기록으로 읽고, 번호별 최대 통화 시간으로 통신비가 길게 이어지는 일을 막을 수 있어요. call.ended 웹훅은 준비 중이에요.

통화가 끝나면 통화 기록의 결과 필드로 결과를 읽어요. 통화가 끝날 때 내 서버로 오는 `call.ended` 웹훅은 준비 중이에요. 통화는 내 음성 에이전트가 BYE로 끊어요. Telkit은 번호마다 정한 최대 통화 시간에 닿은 통화를 끊고, 그 설정도 여기에 있어요.

> [!NOTE]
>
> 통화는 끝난 뒤에 기록돼요. 통화 기록은 통화가 끝나고 30초쯤 뒤에 생겨요. 통화 중인 전화는 통화 기록에 없어요.

아래 요청은 모두 `Authorization: Bearer <액세스 토큰>` 헤더가 필요하고 기준 주소는 `https://api.telkit.io`예요. 에이전트는 [첫 연결](https://telkit.io/docs/connect/agent.md)을 마치고 받은 워크스페이스 자격을 토큰으로 써요. 오류는 언제나 `error.code`와 `error.message`가 들어 있는 JSON으로 돌아와요.

## 통화 결과 필드

`GET /v1/numbers/{id}/calls`의 각 항목과 `GET /v1/calls/{telkit_call_id}`에 아래 필드가 있어요. 기존 필드는 그대로예요.

| 필드 | 값 | 뜻 |
| - | - | - |
| `sip_code` | 100 \~ 699의 정수 또는 `null` | 목적지가 낸 마지막 SIP 응답 코드예요. 모르면 `null`이에요 |
| `sip_reason` | 문자열 또는 `null` | `sip_code`의 표준 문구예요. `Busy Here`처럼 코드로 만든 문구이고 망이 보낸 문구는 아니에요 |
| `ended_by` | `caller`, `callee`, `system` 또는 `null` | 누가 끊었는지예요. `caller`는 전화를 건 쪽이고 `callee`는 받은 쪽이에요. 내 번호로 걸려 온 통화에서 `callee`는 내 SIP 목적지예요. `system`은 회선이 끊은 경우로 최대 통화 시간, 음성 끊김, 정책이 있어요. 모르면 `null`이에요 |
| `reason` | `max_duration` 또는 `null` | 끝난 이유 코드예요. 번호의 최대 통화 시간에 닿아 끊긴 통화만 `max_duration`이에요. 새 값이 늘 수 있으니 모르는 값은 무시해 주세요 |
| `destination` | 문자열 또는 `null` | 수신 통화가 넘어간 목적지 주소예요. 통화 기록을 만들 때의 연결로 추정해요. 연결을 저장한 뒤 2분 안에 시작했거나 기록되기 전에 연결이 바뀌어 목적지를 확인할 수 없으면 `null`이에요. 안내로 끝난 통화도 `null`이에요. 한 번 기록한 주소는 이후 연결을 바꿔도 유지돼요 |
| `billable_seconds` | 정수 | 요금을 매기는 초예요. 요금을 매기는 통화는 `duration_sec`과 같고, 요금을 매기지 않는 통화는 0이에요. `duration_sec`은 언제나 통화 시간이에요 |
| `result_text` | 문자열 또는 `null` | 통화 결과를 풀어 쓴 한국어 한 문장이에요. 문구는 바뀔 수 있으니 코드에서 나누려면 `sip_code`와 `ended_by`를 써 주세요 |

통화 한 건은 이렇게 보여요.

```json theme={null}
{
  "id": "5d1f0c3e-7c1a-4c0e-9d51-0a9a8f1e2b33",
  "telkit_call_id": "9bbb56e8486f0cb13c46b9c64a45ae6d2e87a172c6fd7d670-0007-6998",
  "number_id": "5b1e0d52-7c1a-4f0e-9d1e-0a8f6a3c9e77",
  "direction": "inbound",
  "peer_e164": "+821012345678",
  "peer_type": "mobile",
  "started_at": "2026-10-01T02:10:00Z",
  "answered_at": "2026-10-01T02:10:03Z",
  "ended_at": "2026-10-01T02:11:08Z",
  "duration_sec": 65,
  "billable": false,
  "charge_krw": 0,
  "billed": false,
  "billable_seconds": 0,
  "sip_code": 200,
  "sip_reason": "OK",
  "ended_by": "callee",
  "reason": null,
  "destination": "sip:agent@pbx.example.com;transport=tls",
  "result_text": "통화 뒤 받은 쪽이 끊었어요."
}
```

목적지가 받지 않은 통화는 `answered_at`이 `null`이고 `duration_sec`이 0이에요. 이유는 `sip_code`와 `result_text`에 있어요. 관련 필드만 보면 이래요.

```json theme={null}
{
  "answered_at": null,
  "duration_sec": 0,
  "sip_code": 486,
  "sip_reason": "Busy Here",
  "destination": "sip:agent@pbx.example.com;transport=tls",
  "result_text": "목적지가 통화 중이에요."
}
```

## 사유 표

`result_text`에 들어가는 문장이에요. Telkit이 보내는 문장을 그대로 옮겼어요.

### 연결되지 않은 통화

전화가 연결되지 않은 통화는 목적지의 마지막 응답 코드로 설명해요.

| `sip_code` | `sip_reason` | `result_text` |
| - | - | - |
| 400 | `Bad Request` | 요청 형식이 맞지 않아 목적지가 받지 않았어요. |
| 401 | `Unauthorized` | 목적지가 인증을 요구했어요. 목적지가 Telkit의 전화를 인증 없이 받도록 열어 주세요. |
| 403 | `Forbidden` | 목적지가 전화를 거절했어요. 목적지에서 Telkit의 접속을 허용했는지 확인해 주세요. |
| 404 | `Not Found` | 목적지에 이 번호나 사용자가 없어요. 주소의 사용자 부분을 확인해 주세요. |
| 408 | `Request Timeout` | 목적지가 시간 안에 응답하지 않았어요. |
| 480 | `Temporarily Unavailable` | 목적지가 지금 전화를 받을 수 없어요. |
| 486 | `Busy Here` | 목적지가 통화 중이에요. |
| 487 | `Request Terminated` | 전화를 건 쪽이 연결되기 전에 끊었어요. |
| 488 | `Not Acceptable Here` | 목적지가 음성 조건을 받아들이지 않았어요. 코덱과 SRTP 설정을 확인해 주세요. |
| 500 | `Server Internal Error` | 목적지 서버에 오류가 났어요. |
| 502 | `Bad Gateway` | 목적지까지 연결하지 못했어요. 주소와 전송 방식(TLS·TCP·UDP)을 확인해 주세요. |
| 503 | `Service Unavailable` | 목적지가 지금 요청을 받을 수 없어요. 서버 상태와 주소를 확인해 주세요. |
| 504 | `Server Time-out` | 목적지가 시간 안에 응답하지 않았어요. |
| 600 | `Busy Everywhere` | 목적지가 전화를 받을 수 없다고 답했어요. |
| 603 | `Decline` | 목적지가 전화를 거부했어요. |

표에 없는 코드는 등급으로 설명해요.

| `sip_code` | `result_text` |
| - | - |
| 그 밖의 4xx | 목적지가 전화를 받지 않았어요. |
| 그 밖의 5xx | 목적지나 회선에 오류가 있어 연결하지 못했어요. |
| 그 밖의 6xx | 목적지가 전화를 받을 수 없다고 답했어요. |

1xx, 2xx, 3xx는 연결되지 않은 통화의 실패 코드가 아니라서 `result_text`가 `null`이에요.

### 연결된 통화

통화가 연결됐다가 끝난 경우는 `ended_by`로 설명해요.

| `ended_by` | `result_text` |
| - | - |
| `caller` | 통화 뒤 전화를 건 쪽이 끊었어요. |
| `callee` | 통화 뒤 받은 쪽이 끊었어요. |
| `system` | 통화 중 회선이 끊었어요. 시간 제한이나 음성 끊김일 수 있어요. |
| `null` | 통화가 연결됐다가 끝났어요. |

`reason`이 `max_duration`이면 `ended_by`와 상관없이 「번호의 최대 통화 시간에 닿아 회선이 끊었어요.」가 나와요.

## 웹훅 받기

> [!NOTE]
>
> 웹훅은 준비 중이에요. 지금은 이 절의 요청이 모두 `503` `not_available`로 돌아와요. 열리기 전에는 위의 통화 결과 필드를 통화 기록 API로 읽어 주세요. 아래는 웹훅이 열린 뒤 쓸 내용이에요.

통화가 끝나고 통화 기록이 생기면 Telkit이 내 서버로 `call.ended` 웹훅을 보내요. 웹훅 주소는 계정마다 하나예요. 이 웹훅은 Telkit이 보내는 것이라 OpenAI 프로젝트에서 받는 `live.transport.incoming` 알림과는 다르고, 서명 비밀값도 따로 있어요.

### 웹훅 주소 만들기

`PUT /v1/webhook-endpoint`에 주소를 보내면 만들어요.

```bash theme={null}
curl -s -X PUT https://api.telkit.io/v1/webhook-endpoint \
  -H "Authorization: Bearer $TELKIT_TOKEN" -H 'Content-Type: application/json' \
  -d '{"url":"https://hooks.example.com/telkit"}'
```

```json theme={null}
{
  "url": "https://hooks.example.com/telkit",
  "enabled": true,
  "secret_hint": "9fQ2",
  "secret_rotated_at": "2026-10-01T02:00:00Z",
  "previous_secret_expires_at": null,
  "created_at": "2026-10-01T02:00:00Z",
  "updated_at": "2026-10-01T02:00:00Z",
  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
}
```

> [!WARNING]
>
> `secret`은 만들 때와 비밀값을 바꿀 때 응답에서 한 번만 보여요. 바로 서버 환경 변수 `TELKIT_WEBHOOK_SECRET`에 저장해 주세요. 다시 볼 수 없어요.

| 요청 | 하는 일 |
| - | - |
| `PUT /v1/webhook-endpoint` | 주소를 만들어요. 처음이면 `201`과 `secret`을 돌려줘요. 이미 있으면 주소만 바꾸고 `200`을 돌려주며 `secret`은 없어요 |
| `GET /v1/webhook-endpoint` | 주소, 웹훅을 보내는 중인지 나타내는 `enabled`, 비밀값의 끝 네 글자 `secret_hint`, `secret_rotated_at`, `previous_secret_expires_at`을 봐요. 비밀값은 나오지 않고 만들지 않았으면 `404` `webhook_endpoint_not_found`예요 |
| `POST /v1/webhook-endpoint/rotate-secret` | 비밀값을 바꿔요. 새 `secret`을 한 번만 돌려줘요 |
| `DELETE /v1/webhook-endpoint` | 주소를 지워요. 이 뒤로는 이벤트를 보내지 않아요. 원래 없었어도 `204`예요 |

주소는 아래 규칙을 지켜야 해요. 어긋나면 `422`로 거절해요.

* `https://`로 시작하는 주소만 받아요. 2048자까지예요.
* 도메인 이름만 받아요. IP 주소, `localhost`, 내부용 이름, Telkit의 도메인은 `webhook_host_not_allowed`예요.
* 사용자 정보 `user:pass@`와 `#조각`은 넣을 수 없어요.
* 쿼리 문자열에 토큰을 넣어도 돼요.
* 그 밖에 주소 모양이 맞지 않으면 `invalid_webhook_url`이에요.

Telkit은 보낼 때마다 도메인 이름을 다시 풀어서 공인 주소로만 연결해요. 리다이렉트는 따라가지 않고, 10초 안에 답이 없으면 실패로 봐요. 응답 본문은 읽지 않아요.

### 이벤트

`call.ended`는 통화가 끝나고 통화 기록이 생긴 뒤에 보내요. 내 번호로 걸려 온 통화와 SIP 트렁크로 내가 건 통화 모두 보내고, `direction`으로 구분해요. 웹훅 주소를 만든 뒤에 끝난 통화부터 보내요. 그 전 통화는 통화 기록 API로 읽어 주세요.

Telkit은 `POST`로 `Content-Type: application/json` 본문을 보내고, 헤더는 [Standard Webhooks](https://www.standardwebhooks.com) 규격을 따라요.

| 헤더 | 값 |
| - | - |
| `webhook-id` | `evt_`로 시작하는 이벤트 ID예요. 다시 보내도 같아서 중복을 거를 때 써요 |
| `webhook-timestamp` | 보낸 시각이에요. 초 단위이고 시도마다 새로 만들어요 |
| `webhook-signature` | `v1,`로 시작하는 서명이에요. 자세한 검증은 아래 [서명 검증](#서명-검증)에 있어요 |

본문은 이런 모양이에요.

```json theme={null}
{
  "id": "evt_0b0a5d5e2a3c4c559f5c2f3e8f6f7a11",
  "type": "call.ended",
  "created_at": "2026-10-01T03:01:10Z",
  "data": {
    "telkit_call_id": "9bbb56e8486f0cb13c46b9c64a45ae6d2e87a172c6fd7d670-0007-6998",
    "direction": "inbound",
    "from": "+821012345678",
    "to": "+827012345678",
    "started_at": "2026-10-01T03:00:00Z",
    "answered_at": "2026-10-01T03:00:05Z",
    "ended_at": "2026-10-01T03:01:05Z",
    "duration": 60,
    "billable_seconds": 60,
    "sip_code": 200,
    "sip_reason": "OK",
    "ended_by": "callee",
    "reason": null
  }
}
```

`data`에는 아래 열세 개 키가 언제나 들어 있고, 모르는 값은 `null`이에요.

| 키 | 값 | 뜻 |
| - | - | - |
| `telkit_call_id` | 문자열 | 통화 ID예요. 통화 기록의 `telkit_call_id`와 같아요 |
| `direction` | `inbound` 또는 `outbound` | `inbound`는 걸려 온 통화, `outbound`는 SIP 트렁크로 내가 건 통화예요 |
| `from` | E.164 번호 | 전화를 건 쪽이에요. 걸려 온 통화는 상대 번호이고 번호를 알리지 않았으면 `unknown`이에요. 내가 건 통화는 내 Telkit 번호예요 |
| `to` | E.164 번호 | 전화를 받은 쪽이에요. 걸려 온 통화는 내 Telkit 번호이고, 내가 건 통화는 상대 번호예요 |
| `started_at` | ISO 8601, UTC | 통화가 시작된 시각이에요 |
| `answered_at` | ISO 8601, UTC 또는 `null` | 전화가 연결된 시각이에요. 받지 않았으면 `null`이에요 |
| `ended_at` | ISO 8601, UTC | 통화가 끝난 시각이에요 |
| `duration` | 정수 | 통화 시간 초예요. 연결되지 않았으면 0이고, 통화 기록의 `duration_sec`과 같아요 |
| `billable_seconds` | 정수 | 요금을 매기는 초예요. 무료 통화는 0이에요 |
| `sip_code` | 정수 또는 `null` | 통화 결과 필드의 `sip_code`와 같아요 |
| `sip_reason` | 문자열 또는 `null` | 통화 결과 필드의 `sip_reason`과 같아요 |
| `ended_by` | 문자열 또는 `null` | 통화 결과 필드의 `ended_by`와 같아요 |
| `reason` | 문자열 또는 `null` | 통화 결과 필드의 `reason`과 같아요 |

받는 서버는 이렇게 처리해 주세요.

* `2xx`로 빨리 답해 주세요. 무거운 일은 답한 뒤에 하고, 10초 안에 답하지 않으면 실패로 봐요.
* 같은 `webhook-id`가 다시 오면 한 번만 처리해 주세요.
* 모르는 이벤트 종류와 필드는 무시해 주세요. 새 종류와 필드가 예고 없이 늘 수 있어요.

### 서명 검증

`webhook-signature`는 `v1,`에 이어 `webhook-id.webhook-timestamp.본문`을 HMAC-SHA256으로 서명해 base64로 적은 값이에요. 키는 `whsec_` 뒤의 값을 base64로 푼 것이에요. 직접 계산하지 말고 공식 `standardwebhooks` 라이브러리로 검증해 주세요. 설치는 Node.js에서 `npm i standardwebhooks`, Python에서 `pip install standardwebhooks`예요.

검증할 때 지킬 것은 넷이에요.

* 받은 본문을 가공하지 않은 글자 그대로 넘겨 주세요. JSON으로 바꾼 뒤 다시 글자로 만들면 서명이 맞지 않아요.
* `whsec_`로 시작하는 비밀값을 접두사까지 그대로 넘겨 주세요.
* 검증이 예외를 내면 이벤트를 처리하지 말고 `400`으로 거절해 주세요.
* 허용하는 시간 차이는 기본값인 5분 그대로 두어 주세요.

```ts Node.js theme={null}
import express from "express";
import { Webhook } from "standardwebhooks";

// 웹훅을 만들 때 받은 whsec_ 값을 접두사까지 그대로 넣어요.
const webhook = new Webhook(process.env.TELKIT_WEBHOOK_SECRET as string);
const app = express();
// 처리한 webhook-id. 서버가 여러 대라면 DB나 Redis에 두어요.
const handled = new Set<string>();

type TelkitEvent = { id: string; type: string; data: Record<string, unknown> };

// 서명 검증에는 가공하지 않은 본문이 필요해서 글자 그대로 받아요.
app.post("/telkit/webhook", express.text({ type: "application/json" }), (req, res) => {
  let event: TelkitEvent;
  try {
    event = webhook.verify(req.body, req.headers as Record<string, string>) as TelkitEvent;
  } catch {
    res.status(400).send("invalid signature");
    return;
  }

  const webhookId = req.get("webhook-id") ?? "";
  if (handled.has(webhookId)) {
    res.sendStatus(200);
    return;
  }

  if (event.type === "call.ended") {
    const { telkit_call_id, sip_code, ended_by } = event.data;
    console.log("통화 종료", telkit_call_id, sip_code, ended_by);
  }

  // 모르는 이벤트 종류도 2xx로 답해요.
  handled.add(webhookId);
  res.sendStatus(200);
});

app.listen(8000);
```

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

from flask import Flask, request
from standardwebhooks.webhooks import Webhook, WebhookVerificationError

# 웹훅을 만들 때 받은 whsec_ 값을 접두사까지 그대로 넣어요.
webhook = Webhook(os.environ["TELKIT_WEBHOOK_SECRET"])
app = Flask(__name__)
handled: set[str] = set()  # 처리한 webhook-id. 서버가 여러 대라면 DB나 Redis에 두어요.


@app.post("/telkit/webhook")
def telkit_webhook():
    try:
        # 가공하지 않은 본문을 그대로 넘겨요.
        event = webhook.verify(request.get_data(), dict(request.headers))
    except WebhookVerificationError:
        return "invalid signature", 400

    webhook_id = request.headers.get("webhook-id", "")
    if webhook_id in handled:
        return "", 200

    if event["type"] == "call.ended":
        call = event["data"]
        app.logger.info("통화 종료 %s %s %s", call["telkit_call_id"], call["sip_code"], call["ended_by"])

    # 모르는 이벤트 종류도 2xx로 답해요.
    handled.add(webhook_id)
    return "", 200


if __name__ == "__main__":
    app.run(port=8000)
```

### 다시 보내기

`2xx`로 답하면 전달이 끝나요. 그 밖의 상태 코드, 10초를 넘긴 응답, 연결 오류와 인증서 오류는 실패로 보고 아래 간격으로 다시 보내요. `3xx`도 리다이렉트를 따라가지 않고 실패로 봐요.

| 시도 | 앞 시도가 실패한 뒤 기다리는 시간 |
| - | - |
| 1 | 바로 보내요 |
| 2 | 5초 |
| 3 | 5분 |
| 4 | 30분 |
| 5 | 2시간 |
| 6 | 5시간 |
| 7 | 10시간 |
| 8 | 10시간 |

* 처음 시도부터 마지막 시도까지 27시간이 조금 넘어요. 여덟 번 시도해도 받지 못하면 그 이벤트는 버려요.
* `410`으로 답하면 그 이벤트는 다시 보내지 않아요.
* 다시 보내도 `webhook-id`와 본문은 같고, `webhook-timestamp`와 서명만 새로 만들어요.
* 버린 이벤트는 다시 보내지 않아요. 놓친 통화는 통화 기록 API에서 언제나 읽을 수 있어요.

### 비밀값 바꾸기

`POST /v1/webhook-endpoint/rotate-secret`으로 새 비밀값을 받아요.

```bash theme={null}
curl -s -X POST https://api.telkit.io/v1/webhook-endpoint/rotate-secret \
  -H "Authorization: Bearer $TELKIT_TOKEN"
```

* 새 `secret`은 이 응답에서 한 번만 보여요.
* 옛 비밀값도 24시간 동안 함께 서명해서 `webhook-signature` 헤더에 서명이 둘 실려요. 두 서명은 공백으로 나뉘어 있고, 공식 라이브러리는 하나만 맞아도 통과시켜요. 그 사이에 서버를 새 비밀값으로 바꿔 주세요.
* 옛 비밀값이 끝나는 시각은 `GET /v1/webhook-endpoint`의 `previous_secret_expires_at`에 있어요.
* 24시간 안에 다시 바꾸면 그보다 오래된 비밀값은 사라져요.

## 최대 통화 시간

통화를 끝내는 것은 내 음성 에이전트의 일이에요. 내 음성 에이전트가 통화를 끝내면 BYE를 보내고, Telkit은 그 BYE로 양쪽 통화를 정리해요. Telkit이 통화를 끊는 때는 한 가지예요. 통화 하나가 번호의 최대 통화 시간에 닿으면 회선이 양쪽을 모두 끊어요. 음성 에이전트가 통화를 끝내지 못해도 통신비가 길게 이어지지 않게 하는 안전장치예요.

* 값은 60 \~ 14400초예요. 4시간까지이고 기본은 3600초예요.
* 바꾼 값은 잠시 후부터 새로 걸리는 통화에 적용돼요. 이미 통화 중인 전화는 그대로예요.
* 번호를 해지하면 값이 3600초로 돌아가요.
* 에이전트에게 최대 통화 시간 변경을 요청하면 아래 API로 저장해요.

```bash theme={null}
curl -s -X PUT "https://api.telkit.io/v1/numbers/$NUMBER_ID/max-duration" \
  -H "Authorization: Bearer $TELKIT_TOKEN" -H 'Content-Type: application/json' \
  -d '{"max_duration_sec":1800}'
```

응답은 바뀐 번호 전체이고, `max_duration_sec`이 저장한 값이에요. `GET /v1/numbers/{id}`에서도 볼 수 있어요.

한도에 닿아 끊긴 통화는 통화 기록에 `ended_by`가 `system`, `reason`이 `max_duration`으로 나와요.

| 상태 | `code` | 뜻 |
| - | - | - |
| 422 | `invalid_max_duration` | 60 이상 14400 이하의 정수가 아니에요 |
| 400 | `invalid_request` | 본문 형식이 맞지 않아요. 정수가 아니어도 여기예요 |
| 403 | `number_suspended` | 이용이 정지된 번호예요 |
| 404 | `number_not_found` | 없는 번호이거나 내 번호가 아니에요 |

## 관련 문서

* [첫 통화](https://telkit.io/docs/connect/first-call.md): 번호를 음성 에이전트의 SIP 주소에 잇기
* [OpenAI 연동](https://telkit.io/docs/connect/openai.md): OpenAI 프로젝트로 전화 받기
* [번호와 요금](https://telkit.io/docs/numbers/pricing.md): 통신비와 결제일


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