- **Webhook 엔드포인트**는 안정적인 페이로드와 함께
telephony.complete(전화 통화) 또는web.complete(웹 통화 및 빌더 마이크 테스트 통화)를 수신합니다. 페이로드는 아래에 문서화되어 있으며, 전송별event_id, 30초 제한 시간 및 최대 24시간 재시도가 적용됩니다. - **레거시 단일 URL webhook**은 약간 다른 페이로드로 동기식 시도를 한 번 수신합니다(10초 제한 시간, 재시도 없음). 레거시 페이로드 차이점을 참조합니다.
요청 페이로드(엔드포인트 전송)
종료 사유
트랜스크립트 형식
transcripts의 각 항목은 하나의 대화 턴입니다. 역할은
user(발신자 음성), model(에이전트 음성 및 도구 호출),
tool(도구 결과), system(언어 전환 등의 통화 이벤트)입니다.
중단 마커, 맞장구 프롬프트 및 원시 위치를 포함한 완전히 구조화된 턴 기록은
GET /v1/calls/{call_id}/history를 사용하세요.
레거시 페이로드 차이점
레거시 단일 URL 웹훅 엔벨로프는{"type": "telephony.complete" | "web.complete", "data": {…}}이며,
event_id가 없고 data가 엔드포인트 페이로드와 다릅니다.
- 턴 배열은
transcripts가 아니라history아래에 있습니다(위와 동일한 턴 스키마). - 필드 집합은 통화 종료 시의 원시 보고서이며, 위 표에 없는 추가 내부 필드를 포함할 수 있습니다. 알 수 없는 필드는 정보용으로 처리하세요.
- 웹 통화(
direction: "web")는from_number/to_number를 생략하고origin_domain을 추가합니다. - Builder 마이크 테스트 통화는 레거시 경로에서
telephony.complete로 보고됩니다(엔드포인트 시스템은 이를web.complete로 매핑합니다). - 전송 조정: 통화가 전송 중에 종료되면 레거시 웹훅은 동기식으로 호출되며, 인계 대상이 준비되지 않았음을 알리기 위해
{"transfer_ready": false}를 응답할 수 있습니다. 그 밖의 모든 응답(또는 레거시 웹훅이 없는 경우)은 전송이 진행되도록 합니다. 이 경우 엔드포인트 전송은 참조되지 않습니다.
예제 핸들러
일반적인 사용 사례
CRM 통합
각 통화의 트랜스크립트와 녹음 URL을 고객 기록과 함께 저장합니다.
분석
토픽 모델링, CSAT 신호 추출 또는 전환율 모니터링을 위해 트랜스크립트를 파이프라인으로 스트리밍합니다.
품질 검토
사람이 검토할 수 있도록 QA 도구에서 통화를 열거나 자체 평가 모델로 실행합니다.
알림
전환 또는 실패 시 담당 팀원에게 알림을 보냅니다.
관련 항목
telephony.incoming / web.incoming
통화 시작 시 실행되는 차단형 대응 이벤트입니다.
이벤트 카탈로그
구독할 수 있는 다른 이벤트 유형입니다.
통화 기록 API
백필 또는 재생을 위해 REST를 통해 동일한 데이터에 액세스할 수 있습니다.