이벤트 카탈로그

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

엔드포인트 전달은 항상 재시도가 적용되는 비차단 알림입니다. 모든 2xx로 응답합니다. 중복 제거에는 봉투의 event_id를 사용합니다.
차단 교환은 레거시 단일 URL 웹훅에서만 실행됩니다. telephony.incoming / web.incoming 구성 요청(웹훅 모드 번호 및 위젯 키, 10초 제한 시간)과 웹훅 모드 도구 디스패치가 이에 해당합니다. 응답이 진행 중인 통화를 결정합니다.

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

통화 이벤트

`telephony.incoming`

수신 통화가 전화번호 중 하나에 도달하면 전송됩니다. 엔드포인트 전송은 번호가 에이전트로 구성되었는지 또는 웹훅으로 구성되었는지와 관계없이 모든 수신 통화에 대해 전송되는 fire-and-forget 알림입니다. 에이전트가 할당되지 않은 번호는 레거시 웹훅에서 추가로 차단형 구성 요청을 수신합니다. 전체 요청/응답 스키마는 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의 웹 채널 대응 이벤트입니다. 엔드포인트 전송은 모든 웹 세션에 대한 fire-and-forget 알림입니다. 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의 웹 채널 대응 이벤트입니다. 비차단형입니다. telephony.complete과 동일한 페이로드 형태에 origin_domain이 추가되며, from_number는 "web"으로 설정됩니다.

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

`web.tool`

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

품질 이벤트

`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`

품질 이벤트

`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

​품질 이벤트

​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`

품질 이벤트

`call.graded`

`issue.reported`

테스트 통화 이벤트

`test-call.completed`

알림 이벤트

`alert.triggered`

관련 항목