> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryvox.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 채팅 인바운드 웹훅

> 채널로 들어온 고객의 메시지로 새 채팅이 열리면 내 서버에서 고객 정보를 받아 첫 답변 전에 동적 변수와 메타데이터로 넣을 수 있어요.

채팅 인바운드 웹훅은 카카오톡, 문자 같은 연결된 채널로 고객이 보낸 메시지가 새 채팅을 열면, 채널과 고객을 구분하는 값을 내 서버로 보내고 서버가 돌려준 값을 그 채팅의 [동적 변수](https://docs.tryvox.co/docs/build/variables/dynamic-variables.md)와 메타데이터로 넣어요. 채널로 먼저 연락한 고객의 회원 정보를 첫 답변부터 쓰게 할 수 있어요. 전화는 [인바운드 웹훅](https://docs.tryvox.co/docs/build/variables/inbound-webhook.md)이 같은 일을 해요.

API(`POST /v3/chats`), 문자 발신 시작(`POST /v3/chats/sms`), 위젯으로 만드는 채팅에는 요청을 보내지 않아요. 이 채팅에는 만들 때 넣은 `dynamic_variables`, `metadata`를 써요.

## 채팅 인바운드 웹훅 연결하기

**1. 수신 서버 만들기**

아래 [요청과 응답](#요청과-응답) 형식대로 답하는 HTTPS 엔드포인트를 준비하세요. 예시는 [서버 구현 예시](#서버-구현-예시)에 있어요.

**2. 채팅 인바운드 웹훅 URL 넣기**

에이전트 설정의 **웹훅 설정**을 열고 **채팅 인바운드 웹훅 URL**에 엔드포인트를 넣은 뒤 저장하세요. API로는 에이전트의 `data.webhookSettings.inboundChatWebhookUrl`에 넣어요. URL은 `https://`만 저장되고, URL 자체에는 동적 변수를 쓸 수 없어요.

**3. 프롬프트에 변수 넣기**

응답의 `dynamic_variables` 키와 같은 이름으로 프롬프트에 `{{변수명}}`을 넣으세요. 첫 답변을 만들 때 값으로 바뀌어요.

**4. 실제 채팅으로 확인하기**

[curl로 먼저 시험](#연결-확인)한 뒤 연결한 채널로 메시지를 보내 새 채팅을 열고 변수가 제대로 들어갔는지 보세요.

URL을 저장한 에이전트 버전으로 새로 시작하는 채팅부터 요청을 보내요. 이미 진행 중인 채팅에는 보내지 않아요.

## 요청과 응답

채널로 받은 메시지가 새 채팅을 열면 vox.ai가 채팅 하나에 한 번, 아래 JSON 본문으로 **POST** 요청을 보내요. 필드는 항상 이 다섯 개이고, 해당하지 않는 값은 `null`이에요.

```json theme={null}
{
  "channel": "kakao",
  "chat_channel_id": "3f1c2a9e-7b4d-4c1a-9e2f-8a6b5c4d3e21",
  "widget_id": null,
  "agent": {
    "agent_id": "8a2b6c1d-4e5f-4a7b-9c8d-1e2f3a4b5c6d",
    "agent_version": "v3"
  },
  "channel_user_id": "kakao_user_key_123"
}
```

* **`channel`**: 채팅이 들어온 채널이에요. `sms`, `kakao`, `navertalk`, `instagram`, `line`, `wechat`, `channeltalk` 가운데 하나예요.
* **`chat_channel_id`**: 채팅 조회 API에 나오는 채팅 채널 ID와 같은 값이에요. 등록하지 않은 문자 채널은 `null`이에요.
* **`widget_id`**: 위젯 채팅에는 요청을 보내지 않으므로 지금은 항상 `null`이에요.
* **`agent`**: 응대할 에이전트예요. `agent_version`은 채팅 웹훅과 같은 형식으로 `v{n}`이나 `current`예요.
* **`channel_user_id`**: 그 채널에서 고객을 구분하는 값이에요. 문자는 고객 전화번호, 채널톡은 `user_chat_id`, 다른 메신저는 그 채널의 이용자 키예요.

응답 JSON은 아래 구조를 따라야 해요.

```json theme={null}
{
  "chat_inbound": {
    "dynamic_variables": {
      "customer_name": "김철수",
      "tier": "VIP"
    },
    "metadata": {
      "user_id": "cust_12345"
    }
  }
}
```

* **`dynamic_variables`**: 프롬프트의 `{{변수명}}`에 들어갈 키와 값이에요.
* **`metadata`**: 프롬프트에는 들어가지 않고 채팅의 메타데이터로 저장돼요. 채팅 조회 API와 `chat_started`, `chat_ended`, `chat_analyzed` 채팅 웹훅에서 그대로 읽을 수 있어요. 메시지 이벤트 웹훅에는 실리지 않아요.
* **값이 없을 때**: 해당 고객이 없으면 `chat_inbound`를 빼거나 `{"chat_inbound": {"dynamic_variables": {}}}`처럼 빈 객체로 답하세요. 두 필드는 따로 읽고, 객체가 아닌 필드는 쓰지 않아요.

### 응답 제한

* **시간**: vox.ai가 이 채팅의 웹훅 처리를 시작한 때부터 응답 본문을 다 받을 때까지 5초 안에 끝나야 해요. 요청 준비, 주소 조회, 연결 시간도 이 5초에 들어가므로 서버가 쓸 수 있는 시간은 5초보다 짧아요. 연결 단계에서 시간이 초과되면 한 번만 다시 시도하고, 그 밖에는 다시 보내지 않아요.
* **크기**: 응답 본문은 64KB까지만 읽어요.
* **상태 코드**: 2xx 응답만 값으로 써요. 리다이렉트(3xx)는 따라가지 않아요.

## 서버 구현 예시

```python chat_inbound_server.py theme={null}
from fastapi import FastAPI

app = FastAPI()

@app.post("/chat-inbound")
async def chat_inbound(post_body: dict):
    channel = post_body.get("channel")
    channel_user_id = post_body.get("channel_user_id")
    customer = await db.users.find_by_channel(channel, channel_user_id)  # CRM 조회

    if not customer:
        return {"chat_inbound": {"dynamic_variables": {}}}

    return {
        "chat_inbound": {
            "dynamic_variables": {
                "customer_name": customer["name"],
                "tier": customer["tier"],
            },
            "metadata": {"user_id": customer["id"]},
        }
    }
```

```javascript chat_inbound_server.js theme={null}
const express = require("express");
const app = express();
app.use(express.json());

app.post("/chat-inbound", async (req, res) => {
  const { channel, channel_user_id } = req.body;
  const customer = await db.users.findByChannel(channel, channel_user_id); // CRM 조회

  if (!customer) {
    return res.json({ chat_inbound: { dynamic_variables: {} } });
  }

  res.json({
    chat_inbound: {
      dynamic_variables: {
        customer_name: customer.name,
        tier: customer.tier,
      },
      metadata: { user_id: customer.id },
    },
  });
});
```

## 채팅에서 일어나는 일

```mermaid theme={null}
sequenceDiagram
    participant C as 고객
    participant V as vox.ai
    participant S as 내 서버
    C->>V: 첫 메시지 또는 채팅 시작
    V->>V: 채팅 저장
    V->>S: POST 채팅 인바운드 웹훅
    S-->>V: chat_inbound 응답 (5초 안)
    V->>V: 동적 변수·메타데이터 합치기
    V-->>C: 첫 답변
```

* **첫 답변은 응답을 받은 뒤에 나가요.** 에이전트의 첫 답변은 웹훅 응답이 오거나 5초가 지난 뒤에 만들어요. 그래서 첫 답변이 최대 5초 늦어질 수 있어요.
* **채팅 웹훅도 그 뒤에 보내요.** 그 채팅의 [채팅 웹훅](https://docs.tryvox.co/docs/operate/monitor/webhooks/overview.md)은 웹훅이 끝난 뒤 `chat_started`부터 보낼 순서를 잡고, `chat_started`에 합친 값이 실려요. 서로 다른 요청이 내 서버에 도착하는 순서는 네트워크에 따라 달라질 수 있어요. 첫 채팅 웹훅은 이전보다 최대 약 11초 늦게 도착할 수 있어요.
* **채팅은 바로 저장돼요.** 채팅과 첫 메시지는 웹훅을 기다리지 않고 저장돼요. 그래서 웹훅이 끝나기 전에는 대시보드와 채팅 조회 API에서 동적 변수와 메타데이터가 비어 보일 수 있어요.
* **실패하면 값 없이 이어가요.** 시간 초과, 2xx가 아닌 응답, 64KB를 넘는 본문, 형식 오류는 웹훅 값 없이 채팅을 이어가요. 5초가 지나 늦게 온 응답의 값은 쓰지 않아요.
* **상담사가 맡은 채팅도 보내요.** 상담사가 응대하거나 AI 응답을 끈 채로 시작한 채팅에도 요청을 보내요. 나중에 AI가 맡으면 그때 저장된 값을 써요.

## 보안

### HMAC 서명 검증

에이전트 설정의 **인바운드 웹훅 서명**이 켜져 있고 워크스페이스에 웹훅 서명 키가 있으면 채팅 인바운드 웹훅 요청에 HMAC-SHA256 서명 헤더가 붙어요. 이 스위치는 [인바운드 웹훅](https://docs.tryvox.co/docs/build/variables/inbound-webhook.md)과 같이 쓰고, 기본값은 꺼짐이에요.

| 헤더 | 설명 | 예시 |
| - | - | - |
| `X-Webhook-Timestamp` | 서명을 만든 시점. Unix 초 | `1738900000` |
| `X-Webhook-Signature` | HMAC-SHA256 서명 | `sha256=a1b2c3...` |

서명 키와 검증 방식은 [워크스페이스 단위 웹훅의 HMAC-SHA256 서명](https://docs.tryvox.co/docs/operate/monitor/webhooks/organization.md#hmac-sha256-서명)과 같아요. 서명 키는 대시보드 **설정 > 웹훅**에서 발급해요.

### 엔드포인트 쪽 추가 방어

* **자체 토큰**: URL 경로나 쿼리에 비밀 토큰을 넣고 서버에서 검증하세요. 예: `https://api.example.com/webhook/chat-inbound?token=YOUR_SECRET_TOKEN`
* **요청 검증**: `agent.agent_id`가 내 에이전트인지, `chat_channel_id`가 내가 연결한 채널인지 확인하세요.

## 연결 확인

본문 형식이 고정이라 엔드포인트는 curl로 직접 시험할 수 있어요.

```bash theme={null}
curl -X POST 'https://api.example.com/webhook/chat-inbound' \
  -H 'Content-Type: application/json' \
  -d '{"channel": "kakao", "chat_channel_id": "3f1c2a9e-7b4d-4c1a-9e2f-8a6b5c4d3e21", "widget_id": null, "agent": {"agent_id": "8a2b6c1d-4e5f-4a7b-9c8d-1e2f3a4b5c6d", "agent_version": "current"}, "channel_user_id": "kakao_user_key_123"}'
```

[요청과 응답](#요청과-응답) 형식대로 5초 안에 200 응답이 오는지 먼저 확인한 뒤, 연결한 채널로 메시지를 보내 첫 답변에 변수가 들어갔는지 보세요.

## 예외 상황

| 상황 | 동작 |
| - | - |
| 5초 안에 응답이 끝나지 않음 | 웹훅 값 없이 채팅을 진행해요. 늦게 온 값은 쓰지 않아요 |
| 2xx가 아닌 응답, 리다이렉트 | 웹훅 값 없이 채팅을 진행해요. 다시 보내지 않아요 |
| 응답 본문이 64KB를 넘음 | 값을 하나도 쓰지 않고 채팅을 진행해요 |
| 응답 JSON 형식 오류 | 값을 하나도 쓰지 않고 채팅을 진행해요 |
| `chat_inbound`가 없음 | 정상 응답으로 보고 웹훅 값 없이 진행해요 |
| `dynamic_variables`나 `metadata` 한쪽만 비었거나 없음 | 값이 있는 쪽만 넣어요 |

## 관련 문서

* [인바운드 웹훅](https://docs.tryvox.co/docs/build/variables/inbound-webhook.md): 전화가 걸려 올 때 외부 서버에서 동적 변수 받기
* [동적 변수](https://docs.tryvox.co/docs/build/variables/dynamic-variables.md): 동적 변수 작성 문법과 다른 주입 경로
* [웹훅 개요](https://docs.tryvox.co/docs/operate/monitor/webhooks/overview.md): 채팅 웹훅과 통화 데이터 웹훅
* [워크스페이스 단위 웹훅](https://docs.tryvox.co/docs/operate/monitor/webhooks/organization.md): 웹훅 서명 키 발급과 서명 검증


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