Documentation Index Fetch the complete documentation index at: https://docs.tryvox.co/llms.txt
Use this file to discover all available pages before exploring further.
웹훅을 사용하면 vox.ai 플랫폼과 외부 시스템 간에 실시간으로 데이터를 주고받을 수 있습니다. 에이전트 설정의 웹훅 섹션에서 두 종류의 웹훅을 각각 구성할 수 있습니다.
웹훅 방향 시점 용도 인바운드 웹훅 vox.ai → 외부 서버 → vox.ai 통화 시작 직전 통화 전 동적 변수 주입 통화 데이터 웹훅 vox.ai → 외부 서버 통화 시작 · 중간 이벤트 · 종료 · 분석 완료 시 외부 시스템에 통화 이벤트 전송
인바운드 웹훅 인바운드 웹훅은 통화가 시작되기 직전 외부 시스템에 발신/수신 번호를 보내고, 응답으로 받은 키-값 쌍을 에이전트의 동적 변수 로 주입합니다. 앞단 CRM에서 고객 정보를 조회해 에이전트 프롬프트에 바로 연결할 수 있습니다.
요청 (vox.ai → 외부 서버) :{ "call_from" : "01012345678" , "call_to" : "0212345678" }
응답 (외부 서버 → vox.ai) :{ "call_inbound" : { "dynamic_variables" : { "user_name" : "홍길동" }, "metadata" : { "user_id" : "17632" } } }
인바운드 웹훅 전체 가이드 웹훅 URL 설정, 타임아웃·재시도 정책, 서버 구현 예시 (Python/JS), 보안 권장
사항, SIP 헤더 보조 수단, 예외 상황까지 다룹니다.
통화 데이터 웹훅 통화 데이터 웹훅은 통화의 주요 이벤트가 발생할 때마다 외부 시스템으로 페이로드를 전송합니다. CRM 연동, 실시간 모니터링, 로그 수집, 통화 후 스크립트 저장 등에 활용합니다.
이 섹션은 v2를 기준으로 설명합니다. 새 연동은 v2로 구현하세요.
v2는 통화 종료 이벤트와 분석 완료 이벤트를 분리합니다.
이벤트 유형 이벤트 시점 설명 call_started통화 시작 통화가 연결된 직후 발생합니다. mid_call통화 진행 중 플로우 노드 전환(flow_transition)이나 개별 발화(call_message)가 발생할 때마다 전송됩니다. call_ended통화 종료 통화가 끝난 뒤 기본 통화 정보와 스크립트를 전송합니다. call_analyzed분석 완료 비용, 요약, 감정 분석, 통화 정보 추출 결과가 준비되면 전송합니다.
최상위 페이로드 구조 모든 이벤트는 공통으로 event 필드를 가집니다.
v2는 webhook_version을 함께 보내고, 모든 이벤트를 call 객체 안에 담아 전송합니다.
{ "event" : "call_started | mid_call | call_ended | call_analyzed" , "webhook_version" : "v2" , "call" : {} }
v1은 기존 수신 서버를 유지해야 하는 경우를 위한 형식입니다.
call_started, call_ended는 call 객체를 사용하고, mid_call은 mid_call 객체를 사용합니다. { "event" : "call_started | call_ended | mid_call" , "call" : {}, "mid_call" : {} }
v2 페이로드 예시 아래 예시는 새 연동에서 구현해야 하는 v2 기준 페이로드입니다.
call_ended는 통화 종료 데이터와 스크립트를 전송합니다.
비용과 분석 결과는 call_analyzed로 전송됩니다.
call_started{ "event" : "call_started" , "webhook_version" : "v2" , "call" : { "call_id" : "6b0f1f08-1c2b-4f0e-9c3a-0c1d9e6f5a82" , "agent" : { "agent_id" : "a1f4c8d2-3e5b-4a7c-9d8e-2b1f6c4a9d3e" , "agent_version" : "v3" }, "call_type" : "inbound" , "from_number" : "01012345678" , "to_number" : "07012345678" , "dynamic_variables" : { "customer_name" : "김철수" }, "metadata" : { "campaign" : "봄_프로모션" }, "start_at" : 1775980200000 , "opt_out_sensitive_data_storage" : false } }
mid_call{ "event" : "mid_call" , "webhook_version" : "v2" , "call" : { "call_id" : "6b0f1f08-1c2b-4f0e-9c3a-0c1d9e6f5a82" , "agent" : { "agent_id" : "a1f4c8d2-3e5b-4a7c-9d8e-2b1f6c4a9d3e" , "agent_version" : "v3" }, "occurred_at" : 1775980380000 , "event_type" : "call_message" , "event_data" : { "role" : "user" , "content" : "주문 번호는 ORD-2026-0042입니다." } } }
call_ended{ "event" : "call_ended" , "webhook_version" : "v2" , "call" : { "call_id" : "6b0f1f08-1c2b-4f0e-9c3a-0c1d9e6f5a82" , "agent" : { "agent_id" : "a1f4c8d2-3e5b-4a7c-9d8e-2b1f6c4a9d3e" , "agent_version" : "v3" }, "call_type" : "inbound" , "from_number" : "01012345678" , "to_number" : "07012345678" , "dynamic_variables" : { "customer_name" : "김철수" }, "metadata" : { "campaign" : "봄_프로모션" }, "call_status" : "ended" , "disconnection_reason" : "agent_hangup" , "start_at" : 1775980200000 , "end_at" : 1775980542000 , "transcript" : [ { "role" : "agent" , "content" : "안녕하세요, 무엇을 도와드릴까요?" }, { "role" : "user" , "content" : "주문 상태를 확인하고 싶습니다." } ], "recording_url" : "https://www.tryvox.co/api/store/download/..." , "opt_out_sensitive_data_storage" : false } }
call_analyzed{ "event" : "call_analyzed" , "webhook_version" : "v2" , "call" : { "call_id" : "6b0f1f08-1c2b-4f0e-9c3a-0c1d9e6f5a82" , "agent" : { "agent_id" : "a1f4c8d2-3e5b-4a7c-9d8e-2b1f6c4a9d3e" , "agent_version" : "v3" }, "call_type" : "inbound" , "from_number" : "01012345678" , "to_number" : "07012345678" , "dynamic_variables" : { "customer_name" : "김철수" }, "metadata" : { "campaign" : "봄_프로모션" }, "call_status" : "ended" , "disconnection_reason" : "agent_hangup" , "start_at" : 1775980200000 , "end_at" : 1775980542000 , "transcript" : [ { "role" : "agent" , "content" : "안녕하세요, 무엇을 도와드릴까요?" }, { "role" : "user" , "content" : "주문 상태를 확인하고 싶습니다." } ], "recording_url" : "https://www.tryvox.co/api/store/download/..." , "call_cost" : { "total_cost" : 120 }, "call_analysis" : { "summary" : "고객이 주문 상태를 문의했고, 상담원이 배송 예정일을 안내했습니다." , "user_sentiment" : "positive" , "custom_analysis_data" : [ { "name" : "inquiry_type" , "value" : "배송 상태 문의" }, { "name" : "resolved" , "value" : true } ] }, "opt_out_sensitive_data_storage" : false } }
시간 필드는 모두 UNIX 타임스탬프 밀리초 단위입니다.
v2에는 duration_ms가 없으므로 end_at - start_at으로 계산하세요.
agent.agent_version은 특정 배포 버전이면 v3처럼 표시되고, 현재 설정으로 실행된 통화면 current입니다.
v1 예시는 기존 수신 서버와의 호환을 위해 제공합니다.
새 연동에서는 위의 v2 페이로드를 기준으로 구현하세요. v1 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" : "01012345678" , "call_to" : "07012345678" , "dynamic_variables" : { "customer_name" : "김철수" }, "metadata" : { "campaign" : "봄_프로모션" }, "start_timestamp" : 1775980200000 , "opt_out_sensitive_data_storage" : false } }
v1 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" : "01012345678" , "call_to" : "07012345678" , "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만 과금 편의를 위해 초 단위로 제공됩니다.
v1에서는 통화 정보 추출 에서 정의한 필드가 call.call_analysis.custom_analysis_data 배열에 포함됩니다. v2에서는 같은 데이터가 call_analyzed 이벤트에 포함됩니다. v1 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, call_analyzed, mid_call, 페이로드, payload, webhook v2
