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

# 이벤트

> 게이트웨이가 보내는 이벤트 13종과 각각 채워지는 필드를 정리했어요.

## 할 수 있는 일

게이트웨이가 보내는 이벤트를 타입별로 구독해요. 핸들러는 동기·비동기 모두 되고 등록 순서대로
처리돼요. 핸들러가 예외를 던져도 수신 루프는 죽지 않아요.

원본 프레임은 언제나 `raw`에서 볼 수 있어요. SDK가 승격하지 않은 필드가 필요할 때 쓰세요.

<Warning>
  핸들러는 **연결 전에** 등록하세요. 연결 후 등록하면 초기 프레임을 놓쳐요.
</Warning>

## 공통 필드

통화 스트림 이벤트는 `type`·`version`·`sessionId`·`callId`·`timestamp`를 공통으로 실어요.

`call.summary`와 `error`는 스트림 이벤트가 아니라 명령 응답이에요. 게이트웨이가
`sessionId`·`timestamp`를 보내지 않으므로 두 필드가 비어 있어요.

필드명 표기는 언어별 관례를 따라요. Python은 `snake_case`(`turn_index`), Go는
`PascalCase`(`TurnIndex`)예요.

## 통화 진행

| 이벤트                  | 채워지는 필드                    | 언제 오나                              |
| -------------------- | -------------------------- | ---------------------------------- |
| `call.created`       | (공통 필드만)                   | `createCall` 직후. `callId`를 여기서 받아요 |
| `call.statusChanged` | `status`, `previousStatus` | 상태 전이. 취소도 여기로 와요                  |
| `user.turn`          | `turnIndex`, `text`        | 상대 발화. 답변할 차례                      |
| `agent.turn`         | `turnIndex`, `text`        | 내 답변이 실제로 발화됨                      |

`call.created`가 초기 상태 `queued`를 뜻해요. `call.statusChanged`는 상태가 `queued`에서
바뀐 뒤부터 와요.

## 명령 응답

| 이벤트               | 채워지는 필드                                                                                      | 언제 오나                                                |
| ----------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `answer.accepted` | `requestId`, `messageId`                                                                     | [answer](/developer/sdk/commands/answer)가 접수됨        |
| `dtmf.accepted`   | `requestId`, `messageId`, `digits`                                                           | [sendDtmf](/developer/sdk/commands/send-dtmf)가 접수됨   |
| `call.summary`    | `requestId`, `callId`, `status`, `durationSeconds`, `transcript`, `summary`, `creditCharged` | [getSummary](/developer/sdk/commands/get-summary) 응답 |

<Info title="accepted 는 발화 보장이 아니에요">
  명령이 검증되어 넘어갔다는 접수 확인일 뿐이에요. `answer`가 실제로 말해진 것은 뒤따르는
  `agent.turn`으로 확인해요. `sendDtmf`는 톤이라 애초에 `agent.turn`이 없어요.
</Info>

## 종단

| 이벤트              | 채워지는 필드                   | 언제 오나 |
| ---------------- | ------------------------- | ----- |
| `call.completed` | `status`                  | 정상 완료 |
| `call.noAnswer`  | `status`, `failureReason` | 무응답   |
| `call.failed`    | `status`, `failureReason` | 실패    |

종단 이벤트가 오면 통화 스트림이 끝나요. 취소는 종단 이벤트가 아니라
`call.statusChanged`(`status: cancelled`)로 와요. `waitClosed`는 넷 중 아무거나에서 풀려요.

## 그 밖

| 이벤트            | 채워지는 필드                                    | 언제 오나                |
| -------------- | ------------------------------------------ | -------------------- |
| `error`        | `code`, `message`, `requestId`, `question` | 명령 실패. 소켓은 닫히지 않아요   |
| `disconnected` | (없음)                                       | SDK 자체 이벤트. WS가 닫힐 때 |

`auth.ok`는 연결 함수가 내부에서 소비하고 다시 내보내지 않아요.
`call.summary`의 `durationSeconds`·`transcript`·`summary`·`creditCharged`는 null일 수 있어요.

## 통화 상태

`status`와 `previousStatus`에 들어가는 값이에요.

| 상태             | 뜻                               |
| -------------- | ------------------------------- |
| `queued`       | 발신 대기. `call.created` 시점의 초기 상태 |
| `dialing`      | 발신 시작                           |
| `ringing`      | 상대 단말이 울리는 중                    |
| `inProgress`   | 통화 연결됨                          |
| `transferring` | 전환 중                            |
| `completed`    | 정상 종료                           |
| `noAnswer`     | 무응답                             |
| `failed`       | 실패                              |
| `cancelled`    | 취소됨                             |

## 주의사항

* `dialing`·`ringing`은 건너뛸 수 있어요. 이미 응답된 통화는 `inProgress`로 바로 가므로
  중간 상태에 의존하지 마세요.
* 진행 상태는 직전 발행 상태와 중복 제거돼요. 같은 상태가 연속으로 오지 않아요.

## 관련 문서

* [레퍼런스](/developer/sdk/reference)
* [오류](/developer/sdk/errors)
* [시작하기](/developer/sdk/quickstart)