ThunderPhone 2.0을 출시했습니다.별도 문의 없이 분당 2¢부터.출시 소식 보기
시작하기

Webhooks

이벤트 카탈로그

ThunderPhone이 전송하는 모든 웹훅 이벤트 유형입니다.

모든 웹훅 본문에는 값이 이 페이지의 이벤트 유형 중 하나인 type 필드가 있습니다. 엔드포인트를 구독할 때 events 배열에는 원하는 이벤트 유형이 포함되어야 합니다(또는 모든 항목을 구독하려면 비워 두세요. 단, 명시적으로 이름을 지정한 엔드포인트에만 전달되는 턴별 이벤트 telephony.turn / web.turn은 예외입니다).

이러한 이벤트는 두 가지 전달 방식으로 전송됩니다.

  • 엔드포인트 전달은 항상 재시도를 지원하는 비차단 알림입니다. 모든 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>"}입니다.

telephony.turn

전화 통화가 진행 중일 때 음성이 포함된 각 턴마다 전송됩니다. 에이전트의 음성 완료 응답과 발신자의 전사된 턴이 발생하는 시점에 전송됩니다. GET /v1/calls/{call_id}/transcript를 폴링하는 대신 일반 웹훅을 통해 실시간 대화를 추적할 수 있습니다. 차단하지 않습니다.

{
  "data": {
    "call_id": 987654321,
    "entry_type": "completion",
    "from_number": "+14155550199",
    "position": 7,
    "role": "assistant",
    "start_ms": 15200,
    "text": "How many employees does your company have?",
    "to_number": "+15551234567"
  },
  "event_id": "8d3f5a2c-7b1e-4c9a-b6d0-2e4f6a8c0d1e",
  "type": "telephony.turn"
}
필드유형설명
positioninteger통화 기록 내 턴의 인덱스이며, 정렬에 사용하는 안정적인 식별자입니다
rolestringassistant(에이전트 음성) 또는 user(발신자 음성)입니다
textstring전송 시점에 알려진 턴의 대화 기록 텍스트입니다
entry_typestring기반 기록 항목 유형입니다. completion(에이전트) 또는 user_turn / span(발신자)입니다
start_ms, end_msinteger통화 시작 이후의 오디오 오프셋(밀리초)이며, 전송 시점에 재생 타이밍이 이미 알려진 경우에만 포함됩니다

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의 웹 채널 버전입니다. 차단하지 않습니다. telephony.complete와 동일한 페이로드 형태에 origin_domain이 추가되며, from_number는 "web"으로 설정됩니다.

web.tool

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

web.turn

웹 위젯 통화 및 빌더 마이크 테스트 통화를 처리하는 telephony.turn의 웹 채널 버전입니다. 페이로드 형태는 동일하지만 from_number / to_number 대신 origin_domain을 사용합니다. telephony.turn과 마찬가지로 명시적 구독이 필요하며, 비어 있는 events 배열을 통해서는 전송되지 않습니다.

음성 이벤트

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

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.idstring사용자 지정 음성 공개 ID
voice.namestringcustom:<public_id> 형식의 에이전트 음성 값
voice.display_namestring조직에 표시되는 음성 이름
voice.languagestring클론의 단일 언어 코드
voice.genderstringmale, female 또는 빈 문자열
voice.statusstringvoice.ready의 경우 ready, voice.failed의 경우 failed
voice.failure_reasonstring성공 시 비어 있으며, 실패 시 처리 실패 세부 정보
voice.created_at, voice.updated_attimestampISO 8601 타임스탬프
reasonstring실패 세부 정보이며 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.idinteger평가 ID
grade.scoreinteger | null0–100
grade.call_outcomestringsuccess, failure, unknown 또는 no_conversation
grade.summarystring한 단락 요약
grade.detected_issuesarray평가기가 발견한 이슈 문자열
grade.statusstring항상 completed — 완료된 실행만 전송됩니다
grade.grader_modelstring결과를 생성한 평가기(예: heuristic-v1)
grade.graded_at, grade.created_attimestamp

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.severitystringcritical, warning 또는 info
issue_report.statusstringopen 또는 resolved
issue_report.sourcestringuser(대시보드에서 등록) 또는 system(평가로 생성)

테스트 통화 이벤트

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_typestringagent 또는 phone_number
test_call_run.target_idintegertarget_type과 일치하는, 실행 대상 에이전트 ID 또는 전화번호 ID
test_call_run.statusstringcompleted 또는 failed
test_call_run.call_idinteger | null통화가 연결되기 전에 실행이 실패한 경우 null
test_call_run.error_messagestring성공 시 비어 있음

알림 이벤트

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_nameUUID, 문자열실행된 규칙입니다.
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 이벤트가 생성되는 방식입니다.