> ## 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.

# 웹훅 이벤트 라이프사이클

> 통화 유형별로 어떤 웹훅 이벤트가 언제 전송되는지 확인하고, 수신 서버에서 처리할 이벤트를 정하세요.

통화 데이터 웹훅은 통화 유형에 따라 전송되는 이벤트와 시점이 달라집니다. 어떤 이벤트를 기다렸다가 무엇을 처리할지 여기서 확인하세요.

## AI 통화만 있을 때

에이전트가 처음부터 끝까지 응대한 통화입니다. 통화 이벤트 4종만 전송됩니다. 아래 차트에서 막대는 통화 구간, 마름모는 웹훅이 전송되는 시점입니다.

```mermaid theme={null}
gantt
    dateFormat YYYY-MM-DD HH:mm:ss
    axisFormat %M:%S
    section 웹훅
        call_started :milestone, w1, 2024-01-01 00:00:00, 0s
        mid_call, 발화마다 :milestone, w2, 2024-01-01 00:01:00, 0s
        mid_call :milestone, w3, 2024-01-01 00:02:30, 0s
        call_ended :milestone, w4, 2024-01-01 00:04:00, 0s
        call_analyzed :milestone, w5, 2024-01-01 00:05:00, 0s
    section 통화
        요금 확정과 분석 :done, a2, 2024-01-01 00:04:00, 2024-01-01 00:05:00
        사용자↔에이전트 통화 (4분) :active, a1, 2024-01-01 00:00:00, 2024-01-01 00:04:00
```

* `call_ended`는 통화가 끊긴 직후 전송됩니다. 스크립트와 녹음 URL은 포함되지만 비용과 분석 결과는 포함되지 않습니다.
* `call_analyzed`는 요금 확정과 분석이 끝난 뒤 전송됩니다. 보통 수 초에서 수 분 뒤입니다.

## 즉시 전환했을 때

에이전트가 통화를 넘기는 즉시 빠집니다. 전환 뒤 통화는 vox.ai 밖에서 이어지므로 상담원 통화 이벤트는 없습니다.

```mermaid theme={null}
gantt
    dateFormat YYYY-MM-DD HH:mm:ss
    axisFormat %M:%S
    section 웹훅
        call_started :milestone, w1, 2024-01-01 00:00:00, 0s
        mid_call :milestone, w2, 2024-01-01 00:01:30, 0s
        call_ended :milestone, w3, 2024-01-01 00:03:00, 0s
        call_analyzed :milestone, w4, 2024-01-01 00:09:30, 0s
    section 통화
        사용자↔에이전트 통화 (3분) :active, a1, 2024-01-01 00:00:00, 2024-01-01 00:03:00
        요금 확정과 분석 :done, a3, 2024-01-01 00:08:00, 2024-01-01 00:09:30
        사용자↔상담원 통화, vox.ai 밖 (5분) :done, a2, 2024-01-01 00:03:00, 2024-01-01 00:08:00
```

* `call_ended`는 통화를 넘기는 순간 전송됩니다. `disconnection_reason`은 `call_transfer`입니다. 스크립트와 녹음에는 에이전트 구간만 담깁니다.
* `call_analyzed`는 고객과 상담원의 통화가 끝난 뒤에 전송됩니다. 전환 뒤 발생한 통신료가 합산되어 요금이 확정되기 때문입니다.

## 안내 후 전환했을 때

에이전트가 상담원에게 브리핑한 뒤 고객과 상담원을 연결합니다. 상담원 구간이 상담원 통화로 기록되어 이벤트 6종이 모두 전송됩니다.

```mermaid theme={null}
gantt
    dateFormat YYYY-MM-DD HH:mm:ss
    axisFormat %M:%S
    section 웹훅
        call_started :milestone, w1, 2024-01-01 00:00:00, 0s
        mid_call :milestone, w2, 2024-01-01 00:01:30, 0s
        operator_call_started :milestone, w3, 2024-01-01 00:03:40, 0s
        call_ended :milestone, w4, 2024-01-01 00:03:45, 0s
        operator_call_ended :milestone, w5, 2024-01-01 00:08:40, 0s
        call_analyzed :milestone, w6, 2024-01-01 00:10:10, 0s
    section 통화
        사용자↔에이전트 통화 (3분) :active, a1, 2024-01-01 00:00:00, 2024-01-01 00:03:00
        상담원 호출과 브리핑 (40초) :active, a2, 2024-01-01 00:03:00, 2024-01-01 00:03:40
        요금 확정과 분석 :done, a4, 2024-01-01 00:08:40, 2024-01-01 00:10:10
        사용자↔상담원 통화 (5분) :crit, a3, 2024-01-01 00:03:40, 2024-01-01 00:08:40
```

* `operator_call_started`는 브리핑이 끝나 고객과 상담원이 연결되는 순간 전송됩니다. 상담원이 받지 않으면 전송되지 않고 에이전트가 응대를 이어갑니다.
* `call_ended`는 곧이어 에이전트가 빠질 때 전송됩니다. 상담원 구간이 진행 중이어도 전송됩니다. 전송 시점은 항상 `operator_call_started` 다음입니다.
* `operator_call_ended`는 상담원 구간이 끝날 때 전송됩니다. `call_analyzed`는 요금이 확정된 뒤 전송됩니다. 두 이벤트의 도착 순서는 보장되지 않습니다.

## 순서 규칙

* 통화 이벤트는 `call_started`, `mid_call`, `call_ended`, `call_analyzed` 순서로 전송됩니다. 안내 후 전환에서는 `operator_call_started` → `call_ended` → `operator_call_ended` 순서로 전송됩니다.
* `call_analyzed`는 요금이 확정된 뒤에 전송됩니다. 전환된 통화는 고객과 상담원의 통화가 끝나야 요금이 확정되므로 그만큼 늦어집니다.
* 같은 이벤트가 두 번 이상 전송될 수 있습니다. 통화 이벤트는 `event`와 `call_id`, 상담원 통화 이벤트는 `event`와 `operator_call_id` 조합으로 중복을 걸러내세요. 재시도 규칙은 [전달 보장과 재시도](/docs/operate/monitor/webhooks/schema#전달-보장과-재시도)를 참고하세요.

## 문제가 생겼을 때

<AccordionGroup>
  <Accordion title="call_analyzed가 한참 뒤에 옵니다">
    전환된 통화라면 고객과 상담원의 통화가 끝날 때까지 기다리세요. 요금이 확정된 뒤에 분석이 진행되기 때문입니다. 개인정보 마스킹이 켜진 에이전트의 통화는 마스킹이 끝난 뒤에 전송되어 더 늦습니다.
  </Accordion>

  <Accordion title="disconnection_reason이 call_transfer인데 상담원 통화 이벤트가 없습니다">
    즉시 전환으로 넘긴 통화입니다. 전환 뒤 통화는 vox.ai 밖에서 이어져 기록되지 않습니다. 상담원 구간까지 웹훅으로 받으려면 [안내 후 전환](/docs/build/tools/builtin/transfer-call#전환-방식-고르기)으로 바꾸세요.
  </Accordion>
</AccordionGroup>

## 관련 문서

* [통화 이벤트](/docs/operate/monitor/webhooks/agent) — 이벤트별 설명과 활용 사례
* [웹훅 스키마](/docs/operate/monitor/webhooks/schema) — 이벤트별 필드 레퍼런스
* [통화 전환 도구](/docs/build/tools/builtin/transfer-call) — 즉시 전환과 안내 후 전환의 동작

***

<Accordion title="연관 검색어">
  웹훅 라이프사이클, webhook lifecycle, 이벤트 순서, 통화 전환 웹훅, 즉시 전환 웹훅, 안내 후 전환 웹훅, cold transfer, warm transfer, operator\_call\_started, operator\_call\_ended, call\_ended, call\_analyzed, 상담원 통화 웹훅, 상담사 통화 웹훅
</Accordion>