웹훅을 사용하면 vox.ai 플랫폼과 외부 시스템 간에 실시간으로 데이터를 주고받을 수 있습니다. 에이전트 설정의 웹훅 섹션에서 두 종류의 웹훅을 각각 구성할 수 있습니다.
웹훅 방향 시점 용도 인바운드 웹훅 vox.ai → 외부 서버 → vox.ai 통화 시작 직전 통화 전 동적 변수 주입 통화 데이터 웹훅 vox.ai → 외부 서버 통화 시작 · 중간 이벤트 · 종료 시 외부 시스템에 실시간 이벤트 전송
인바운드 웹훅 인바운드 웹훅은 통화가 시작되기 직전 외부 시스템에 발신/수신 번호를 보내고, 응답으로 받은 키-값 쌍을 에이전트의 동적 변수 로 주입합니다. 앞단 CRM에서 고객 정보를 조회해 에이전트 프롬프트에 바로 연결할 수 있습니다.
요청·응답 포맷, 타임아웃 동작, 설정 방법 등 자세한 내용은 동적 변수 주입 경로로 다루고 있습니다.
인바운드 웹훅으로 동적 변수 주입 동적 변수 문서의 인바운드 웹훅 섹션에서 전체 작동 방식과 설정 가이드를 확인하세요.
통화 데이터 웹훅 통화 데이터 웹훅은 통화의 주요 이벤트가 발생할 때마다 외부 시스템으로 페이로드를 전송합니다. CRM 연동, 실시간 모니터링, 로그 수집, 통화 후 스크립트 저장 등에 활용합니다.
이벤트 유형 이벤트 시점 설명 call_started통화 시작 통화가 연결된 직후 발생합니다. mid_call통화 진행 중 플로우 노드 전환(flow_transition)이나 개별 발화(call_message)가 발생할 때마다 전송됩니다. call_ended통화 종료 통화가 끝난 뒤 스크립트와 분석 결과를 포함해 전송됩니다.
최상위 페이로드 구조 모든 이벤트는 공통으로 event 필드를 가지며, 이벤트에 따라 call 또는 mid_call 객체가 함께 포함됩니다.
{ "event" : "call_started | call_ended | mid_call" , "call" : { /* call_started, call_ended 에서 사용 */ }, "mid_call" : { /* mid_call 에서 사용 */ } }
call_started 페이로드{ "event" : "call_started" , "call" : { "agent_id" : "a1f4c8d2-3e5b-4a7c-9d8e-2b1f6c4a9d3e" , "call_id" : "6b0f1f08-1c2b-4f0e-9c3a-0c1d9e6f5a82" , "call_type" : "inbound" , "call_from" : "+821012345678" , "call_to" : "+827012345678" , "dynamic_variables" : { "customer_name" : "김철수" }, "metadata" : { "campaign" : "봄_프로모션" }, "start_timestamp" : 1775980200000 , "opt_out_sensitive_data_storage" : false } }
call_ended 페이로드{ "event" : "call_ended" , "call" : { "agent_id" : "a1f4c8d2-3e5b-4a7c-9d8e-2b1f6c4a9d3e" , "call_id" : "6b0f1f08-1c2b-4f0e-9c3a-0c1d9e6f5a82" , "call_type" : "inbound" , "call_from" : "+821012345678" , "call_to" : "+827012345678" , "dynamic_variables" : { "customer_name" : "김철수" }, "metadata" : { "campaign" : "봄_프로모션" }, "start_timestamp" : 1775980200000 , "end_timestamp" : 1775980542000 , "duration_ms" : 342000 , "disconnection_reason" : "agent_hangup" , "recording_url" : "https://www.tryvox.co/api/store/download/..." , "transcript" : [ { "role" : "agent" , "content" : "안녕하세요, 무엇을 도와드릴까요?" }, { "role" : "user" , "content" : "주문 상태를 확인하고 싶습니다." } ], "call_cost" : { "total_credits_used" : 120 , "duration_seconds" : 342 }, "call_analysis" : { "summary" : "고객이 주문 ORD-2026-0042의 배송 상태를 문의했고, 3월 25일 도착 예정임을 안내했습니다." , "user_sentiment" : "positive" , "custom_analysis_data" : [ { "name" : "inquiry_type" , "value" : "배송 상태 문의" }, { "name" : "resolved" , "value" : true } ] }, "opt_out_sensitive_data_storage" : false } }
시간 단위 : start_timestamp, end_timestamp는 UNIX 타임스탬프(밀리초 )이고, duration_ms도 밀리초 입니다. ISO 8601 문자열이 아니라는 점에 유의하세요. call_cost.duration_seconds만 과금 편의를 위해 초 단위로 제공됩니다.
통화 정보 추출 에서 정의한 필드는 call.call_analysis.custom_analysis_data 배열에 포함됩니다. 최상위 extraction 필드는 없습니다.mid_call 페이로드mid_call은 통화가 진행되는 동안 발생하는 세부 이벤트를 스트림처럼 전달합니다. event_type에 따라 event_data 구조가 달라집니다.플로우 노드 전환 (flow_transition): { "event" : "mid_call" , "mid_call" : { "agent_id" : "a1f4c8d2-3e5b-4a7c-9d8e-2b1f6c4a9d3e" , "call_id" : "6b0f1f08-1c2b-4f0e-9c3a-0c1d9e6f5a82" , "timestamp" : 1775980380000 , "event_type" : "flow_transition" , "event_data" : { "from_node_id" : "node_1" , "to_node_id" : "node_2" , "from_node_name" : "인사" , "to_node_name" : "주문 조회" } } }
개별 발화 (call_message): { "event" : "mid_call" , "mid_call" : { "agent_id" : "a1f4c8d2-3e5b-4a7c-9d8e-2b1f6c4a9d3e" , "call_id" : "6b0f1f08-1c2b-4f0e-9c3a-0c1d9e6f5a82" , "timestamp" : 1775980380000 , "event_type" : "call_message" , "event_data" : { "role" : "user" , "content" : "주문 번호는 ORD-2026-0042입니다." } } }
종료 사유 (disconnection_reason) call_ended 페이로드의 disconnection_reason에 쓰이는 값 목록과 의미는 통화 기록 → 종료 사유 에서 확인하세요. 대시보드 필터·API 응답과 동일한 값을 사용합니다.관련 문서
웹훅, webhook, 인바운드 웹훅, 통화 데이터 웹훅, call_started, call_ended, mid_call, 페이로드, payload
