이벤트 카탈로그

모든 웹훅 본문에는 이 페이지의 이벤트 유형 중 하나를 값으로 갖는 type 필드가 있습니다. 엔드포인트를 구독할 때는 events 배열에 원하는 이벤트 유형을 포함해야 합니다(모든 이벤트를 구독하려면 비워 둡니다). 이 이벤트는 두 가지 전송 방식으로 전달됩니다.

엔드포인트 전송은 재시도가 적용되는 항상 비차단 알림입니다. 모든 2xx로 응답하며, 중복 제거에 사용할 수 있도록 봉투에 event_id가 포함됩니다.
차단 교환은 레거시 단일 URL 웹훅에서만 실행됩니다. 여기에는 telephony.incoming / web.incoming 구성 요청(웹훅 모드 번호 및 위젯 키, 10초 타임아웃)과 웹훅 모드 도구 디스패치가 포함됩니다. 응답이 진행 중인 통화를 구성합니다.

아래 예제 페이로드는 전송 순서(키는 알파벳순으로 정렬됨: data, event_id, type)의 엔드포인트 봉투를 보여 줍니다. 레거시 전송은 event_id 없이 동일한 data를 전달합니다.

통화 이벤트

`telephony.incoming`

수신 전화가 귀하의 전화번호 중 하나에 도달하면 전송됩니다. 엔드포인트 전달은 에이전트 구성 여부나 웹훅 구성 여부와 관계없이 모든 수신 전화에 대해 전송되는 파이어 앤드 포겟 알림입니다. 에이전트가 할당되지 않은 번호는 레거시 웹훅에서 추가로 차단형 구성 요청을 수신합니다. 전체 요청/응답 스키마는 telephony.incoming / web.incoming을 참조하세요.

{
  "data": {
    "call_id": 987654321,
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  },
  "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
  "type": "telephony.incoming"
}

`telephony.complete`

수신 또는 발신 전화 통화가 종료되면 전송됩니다. 차단되지 않습니다. 사용 가능한 경우 대화 내용, 녹음 URL 및 청구 요약이 포함됩니다. 페이로드 스키마는 telephony.complete / web.complete을 참조하세요.

`telephony.tool`

전화 통화에서 함수 도구를 호출한 후 전송됩니다. 차단되지 않는 감사 알림입니다. 이 이벤트가 전달될 때 도구는 이미 실행되었으며, 내장 도구, 지식 기반 도구, 앱 연결 도구 또는 MCP 도구가 아닌 자체 함수 도구에 적용됩니다.

{
  "data": {
    "arguments": { "date": "2026-04-21" },
    "call_id": 987654321,
    "from_number": "+14155550199",
    "response": {
      "response": { "available_slots": ["9:00 AM", "2:00 PM"] },
      "status": 200
    },
    "to_number": "+15551234567",
    "tool_name": "search_appointments"
  },
  "event_id": "1f0a7c3e-52d4-4a0e-8f4b-b1a6a1c0d9e2",
  "type": "telephony.tool"
}

response는 실행 결과입니다. 성공 시 {"status": <http status>, "response": <your endpoint's JSON>}이고, 실패 시 {"status": <status>, "error": "<message>"}입니다.

`web.incoming`

웹 위젯 세션 또는 빌더 마이크 테스트 통화가 시작될 때 전송되는 telephony.incoming의 웹 채널 대응 이벤트입니다. 엔드포인트 전달은 모든 웹 세션에 대한 파이어 앤드 포겟 방식입니다. mode="webhook"의 게시 가능 키는 레거시 웹훅에서 추가로 차단형 구성 요청을 수신합니다. 이 차단형 요청은 형식이 다르며(origin_domain, publishable_key_prefix, 전화번호 없음)입니다. telephony.incoming / web.incoming을 참조하세요.

{
  "data": {
    "call_id": 987654322,
    "from_number": "web",
    "origin_domain": "https://example.com",
    "publishable_key_prefix": "pk_live_a1b2",
    "to_number": "+15551234567"
  },
  "event_id": "9a2b4c6d-8e0f-4a1b-9c2d-3e4f5a6b7c8d",
  "type": "web.incoming"
}

from_number는 항상 리터럴 "web"입니다. 웹훅 모드 위젯 세션의 경우 to_number는 비어 있습니다(세션의 에이전트 번호는 구성 후 할당됨). 빌더 마이크 테스트 통화의 경우 origin_domain 및 publishable_key_prefix가 비어 있습니다.

`web.complete`

웹 위젯 통화(direction: "web") 및 빌더 마이크 테스트 통화(direction: "test")를 포함하는 telephony.complete의 웹 채널 대응 이벤트입니다. 차단되지 않습니다. from_number가 "web"으로 설정되고 origin_domain이 추가된 것을 제외하면 telephony.complete과 동일한 페이로드 형식입니다.

레거시 단일 URL 웹훅에서는 빌더 마이크 테스트 통화가 이전부터 telephony.complete로 보고됩니다. 여기에서는 direction: "web" 통화만 web.complete 유형을 사용합니다. 엔드포인트 시스템은 웹 통화와 테스트 통화를 모두 web.*에 매핑합니다. 이전 페이로드에는 레거시 direction 값인 widget 또는 mic가 포함될 수 있습니다.

`web.tool`

telephony.tool의 웹 채널 대응 이벤트입니다. data에는 from_number / to_number 대신 origin_domain이 포함됩니다.

음성 이벤트

사용자 지정 음성 생성은 비동기로 처리됩니다. 이러한 비차단 이벤트를 사용하면 폴링하는 대신 최종 결과에 대응할 수 있습니다. 클론 세부정보 엔드포인트를 사용합니다.

`voice.ready`

사용자 지정 음성 처리가 완료되어 에이전트에 할당할 수 있을 때 전송됩니다.

{
  "data": {
    "voice": {
      "created_at": "2026-07-30T14:12:08.317Z",
      "display_name": "Support voice",
      "failure_reason": "",
      "gender": "female",
      "id": "cv_2f6f90b0e9a34ee8b39be7d1",
      "language": "en",
      "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
      "status": "ready",
      "updated_at": "2026-07-30T14:13:31.605Z"
    }
  },
  "event_id": "2d5f0a61-e9b5-4a3c-b684-29d7d9e4b214",
  "type": "voice.ready"
}

`voice.failed`

사용자 지정 음성 처리가 영구적인 실패 상태에 도달했을 때 전송됩니다.

{
  "data": {
    "reason": "audio sample could not be processed",
    "voice": {
      "created_at": "2026-07-30T14:12:08.317Z",
      "display_name": "Support voice",
      "failure_reason": "audio sample could not be processed",
      "gender": "female",
      "id": "cv_2f6f90b0e9a34ee8b39be7d1",
      "language": "en",
      "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
      "status": "failed",
      "updated_at": "2026-07-30T14:13:31.605Z"
    }
  },
  "event_id": "3493e985-1a75-4f77-a10a-e74af440cd31",
  "type": "voice.failed"
}

필드	유형	설명
`voice.id`	string	사용자 지정 음성 공개 ID
`voice.name`	string	`custom:<public_id>` 형식의 에이전트 음성 값
`voice.display_name`	string	조직에 표시되는 음성 이름
`voice.language`	string	클론의 단일 언어 코드
`voice.gender`	string	`male`, `female` 또는 빈 문자열
`voice.status`	string	`voice.ready`의 경우 `ready`, `voice.failed`의 경우 `failed`
`voice.failure_reason`	string	성공 시 비어 있으며, 실패 시 처리 실패 세부정보
`voice.created_at`, `voice.updated_at`	timestamp	ISO 8601 타임스탬프
`reason`	string	실패 세부정보이며 `voice.failed`에만 존재합니다

품질 이벤트

`call.graded`

통화의 AI 채점 실행이 완료될 때마다 전송됩니다. 차단하지 않습니다.

{
  "data": {
    "call_id": 987654321,
    "grade": {
      "call_outcome": "success",
      "created_at": "2026-04-20T18:25:11.002Z",
      "detected_issues": [],
      "graded_at": "2026-04-20T18:25:11.002Z",
      "grader_model": "heuristic-v1",
      "id": 5512,
      "score": 92,
      "status": "completed",
      "summary": "Caller asked about their policy and got a full answer…"
    }
  },
  "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "type": "call.graded"
}

필드	유형	설명
`grade.id`	integer	채점 ID
`grade.score`	integer \| null	0–100
`grade.call_outcome`	string	`success`, `failure`, `unknown` 또는 `no_conversation`
`grade.summary`	string	한 문단 요약
`grade.detected_issues`	array	채점기가 발견한 이슈 문자열
`grade.status`	string	항상 `completed` — 완료된 실행만 전송됩니다
`grade.grader_model`	string	결과를 생성한 채점기(예: `heuristic-v1`)
`grade.graded_at`, `grade.created_at`	timestamp

하나의 통화는 두 번 이상 채점될 수 있습니다. 녹음이 사용 가능해지면 빠른 휴리스틱 채점 뒤에 전체 모델 채점이 이어지는 경우가 많으며, 수동 재채점도 가능합니다. 완료된 각 실행은 자체 call.graded 이벤트를 전송합니다. 가장 최근의 graded_at을 기준으로 처리하세요.

`issue.reported`

이슈 보고서가 생성될 때 전송됩니다 — 대시보드에서 사용자가 등록한 경우(source: "user") 또는 통화 채점으로 자동 생성된 경우(source: "system")입니다. 차단하지 않습니다.

{
  "data": {
    "call_id": 987654321,
    "issue_report": {
      "created_at": "2026-04-20T18:25:11.002Z",
      "description": "Five-second silence before responding to the main question.",
      "id": 4321,
      "severity": "warning",
      "source": "system",
      "status": "open",
      "title": "Agent paused too long"
    }
  },
  "event_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
  "type": "issue.reported"
}

필드	유형	설명
`issue_report.severity`	string	`critical`, `warning` 또는 `info`
`issue_report.status`	string	`open` 또는 `resolved`
`issue_report.source`	string	`user`(대시보드에서 등록) 또는 `system`(채점으로 생성)

통화를 재채점하면 시스템 생성 이슈 보고서가 다시 생성되며, 재생성된 보고서에 대해 issue.reported가 다시 전송됩니다. 근본 문제당 알림을 하나만 받으려면 call_id + title로 중복을 제거하세요.

테스트 통화 이벤트

`test-call.completed`

테스트 통화 실행이 종료 상태에 도달할 때 전송됩니다 — 통화가 시작 단계에서 실패하여 생성되지 않은 실행을 포함해 completed 또는 failed 상태일 때입니다. 차단하지 않습니다. 일괄 CI 실행을 채팅/알림 시스템에 연결하는 데 유용합니다.

{
  "data": {
    "test_call_run": {
      "call_id": 987654321,
      "completed_at": "2026-04-20T18:25:04.822Z",
      "error_message": "",
      "id": 7110,
      "status": "completed",
      "target_id": 12,
      "target_type": "agent"
    }
  },
  "event_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
  "type": "test-call.completed"
}

필드	유형	설명
`test_call_run.target_type`	string	`agent` 또는 `phone_number`
`test_call_run.target_id`	integer	`target_type`과 일치하는, 실행이 대상으로 지정한 에이전트 ID 또는 전화번호 ID
`test_call_run.status`	string	`completed` 또는 `failed`
`test_call_run.call_id`	integer \| null	통화가 연결되기 전에 실행이 실패한 경우 `null`
`test_call_run.error_message`	string	성공 시 비어 있음

알림 이벤트

`alert.triggered`

개발자 웹훅으로 전달 채널이 활성화된 알림 규칙이 임곗값을 넘을 때 전송됩니다. 비차단 방식입니다. 규칙은 한 번 실행된 후 쿨다운을 적용하므로, 지속적인 위반은 쿨다운 기간마다 하나의 이벤트를 생성합니다.

{
  "data": {
    "comparator": "lt",
    "event_id": "b8e6a1d4-2c3f-4a5b-9c8d-7e6f5a4b3c2d",
    "fired_at": "2026-04-20T18:00:00+00:00",
    "metric": "success_rate",
    "metric_value": 71.4,
    "rule_id": "d2c3b4a5-6f7e-4d8c-9b0a-1c2d3e4f5a6b",
    "rule_name": "Success rate below 80%",
    "threshold": 80.0,
    "window_hours": 24
  },
  "event_id": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a",
  "type": "alert.triggered"
}

필드	유형	설명
`event_id` (`data` 내)	UUID	알림 실행 ID입니다. 엔벨로프의 전달 `event_id`와는 다릅니다.
`rule_id`, `rule_name`	UUID, 문자열	실행된 규칙입니다.
`metric`	문자열	`success_rate`, `failure_rate`, `avg_score`, `call_volume` 또는 `suite_regression`
`comparator`	문자열	`lt`, `lte`, `gt` 또는 `gte`
`metric_value`	숫자	규칙이 실행될 때 평가 기간 동안의 메트릭 값입니다.
`threshold`	숫자	구성된 임곗값입니다.
`window_hours`	정수	후행 평가 기간입니다.
`fired_at`	타임스탬프

규칙, 메트릭, 쿨다운 및 이메일 / Slack 채널 생성 방법은 알림 가이드를 참조하세요.

telephony.incoming / web.incoming

반드시 응답해야 하는 차단형 수신 통화 페이로드입니다.

telephony.complete / web.complete

통화 후 대화 내용과 메트릭입니다.

웹훅 엔드포인트

URL을 이러한 이벤트의 일부에 구독합니다.

함수 도구

telephony.tool / web.tool 이벤트가 생성되는 방식입니다.

Webhooks

Function Tools

통화 이벤트

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

음성 이벤트

`voice.ready`

`voice.failed`

품질 이벤트

`call.graded`

`issue.reported`

테스트 통화 이벤트

`test-call.completed`

알림 이벤트

`alert.triggered`

관련 항목

telephony.incoming / web.incoming

telephony.complete / web.complete

웹훅 엔드포인트

함수 도구

​통화 이벤트

​telephony.incoming

​telephony.complete

​telephony.tool

​web.incoming

​web.complete

​web.tool

​음성 이벤트

​voice.ready

​voice.failed

​품질 이벤트

​call.graded

​issue.reported

​테스트 통화 이벤트

​test-call.completed

​알림 이벤트

​alert.triggered

​관련 항목

telephony.incoming / web.incoming

telephony.complete / web.complete

웹훅 엔드포인트

함수 도구

통화 이벤트

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

음성 이벤트

`voice.ready`

`voice.failed`

품질 이벤트

`call.graded`

`issue.reported`

테스트 통화 이벤트

`test-call.completed`

알림 이벤트

`alert.triggered`

관련 항목