Skip to main content

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.

​
개요

이 페이지는 v2 통화 데이터 웹훅을 기준으로 설명합니다. 모든 v2 이벤트는 { "event", "call" } 구조를 사용합니다. 통화 종료와 분석 완료는 별도 이벤트로 전송됩니다.
비용과 분석 결과는 call_analyzed에서 확인하세요. call_ended에는 포함되지 않습니다.

​
이벤트 생명주기

통화 데이터 웹훅은 통화 진행 상태와 분석 완료 상태를 나누어 전달합니다.
call_analyzed는 통화 종료 후 비동기로 도착할 수 있습니다. call_ended에서 비용, 분석 결과, duration_ms를 기대하지 마세요.

​
공통 구조

카테고리필드
envelopeevent, call
전화번호from_number, to_number
시간start_at, end_at, occurred_at
에이전트agent.agent_id, agent.agent_version
상태call_status, disconnection_reason
분석call.call_analysis (call_analyzed)
비용call.call_cost (call_analyzed)

​
call_started

{
  "event": "call_started",
  "call": {
    "call_id": "3079f46c-d141-4cd9-805f-69f212136b66",
    "agent": {
      "agent_id": "7ea3516d-08f6-4129-ab40-a731e379b320",
      "agent_version": "v3"
    },
    "call_type": "inbound",
    "from_number": "01012345678",
    "to_number": "07012345678",
    "dynamic_variables": {
      "customer_name": "홍길동"
    },
    "metadata": {
      "source": "crm"
    },
    "start_at": 1741842354957,
    "opt_out_sensitive_data_storage": false
  }
}
필드타입설명
eventstring고정값 call_started
call.call_idstring통화 ID
call.agent.agent_idstring에이전트 ID
call.agent.agent_versionstring에이전트 버전입니다. 예: current, v3
call.call_typestring통화 유형
call.from_numberstring | null발신 번호
call.to_numberstring | null수신 번호
call.dynamic_variablesobject통화에 주입된 동적 변수
call.metadataobject통화 메타데이터
call.start_atnumber | null통화 시작 시각입니다. Unix 밀리초입니다.
call.opt_out_sensitive_data_storageboolean민감 데이터 저장 금지 여부

​
mid_call

{
  "event": "mid_call",
  "call": {
    "call_id": "3079f46c-d141-4cd9-805f-69f212136b66",
    "agent": {
      "agent_id": "7ea3516d-08f6-4129-ab40-a731e379b320",
      "agent_version": "v3"
    },
    "occurred_at": 1742158401445,
    "event_type": "call_message",
    "event_data": {
      "role": "user",
      "content": "주문한 제품이 언제 도착하나요?"
    }
  }
}
필드타입설명
eventstring고정값 mid_call
call.call_idstring통화 ID
call.agent.agent_idstring에이전트 ID
call.agent.agent_versionstring에이전트 버전입니다.
call.occurred_atnumber이벤트 발생 시각입니다. Unix 밀리초입니다.
call.event_typestring세부 이벤트 유형입니다.
call.event_dataobject세부 이벤트 데이터입니다.

​
call_ended

{
  "event": "call_ended",
  "call": {
    "call_id": "3079f46c-d141-4cd9-805f-69f212136b66",
    "agent": {
      "agent_id": "7ea3516d-08f6-4129-ab40-a731e379b320",
      "agent_version": "v3"
    },
    "call_type": "inbound",
    "from_number": "01012345678",
    "to_number": "07012345678",
    "dynamic_variables": {
      "customer_name": "홍길동"
    },
    "metadata": {
      "source": "crm"
    },
    "call_status": "ended",
    "disconnection_reason": "user_hangup",
    "start_at": 1741842354957,
    "end_at": 1741842393999,
    "transcript": [
      {
        "role": "agent",
        "content": "주문번호를 확인해드릴게요.",
        "start_at": 1741842358000,
        "end_at": 1741842361000
      },
      {
        "role": "tool_call_invocation",
        "tool_call_id": "tc_001",
        "name": "lookup_order",
        "arguments": {
          "order_id": "ORD-1234"
        }
      },
      {
        "role": "tool_call_result",
        "tool_call_id": "tc_001",
        "content": "{\"status\":\"shipped\",\"eta\":\"2026-04-30\"}"
      },
      {
        "role": "user",
        "content": "감사합니다.",
        "start_at": 1741842370000,
        "end_at": 1741842371200
      }
    ],
    "recording_url": "https://www.tryvox.co/api/store/download/...",
    "opt_out_sensitive_data_storage": false
  }
}
필드타입설명
eventstring고정값 call_ended
call.call_idstring통화 ID
call.agent.agent_idstring에이전트 ID
call.agent.agent_versionstring에이전트 버전입니다.
call.call_typestring통화 유형
call.from_numberstring | null발신 번호
call.to_numberstring | null수신 번호
call.dynamic_variablesobject통화에 주입된 동적 변수
call.metadataobject통화 메타데이터
call.call_statusstring통화 상태입니다. 값은 ended, error, canceled, not_connected, queued, ongoing 중 하나입니다.
call.disconnection_reasonstring | null종료 사유
call.start_atnumber | null통화 시작 시각입니다. Unix 밀리초입니다.
call.end_atnumber | null통화 종료 시각입니다. Unix 밀리초입니다.
call.transcriptarray | null도구 호출을 포함한 스크립트입니다.
call.recording_urlstring | null녹음 파일 URL
call.opt_out_sensitive_data_storageboolean민감 데이터 저장 금지 여부
call_ended에는 비용, 분석 결과, duration_ms가 포함되지 않습니다. 통화 시간은 end_at - start_at으로 계산하세요. 비용과 분석 결과는 call_analyzed에서 확인하세요.

​
스크립트 형식

transcript는 발화와 도구 호출 기록을 한 배열에 담습니다. 도구를 사용하지 않은 통화에는 agent와 user 항목만 포함될 수 있습니다.
role주요 필드설명
agentcontent, start_at, end_at에이전트 발화
usercontent, start_at, end_at사용자 발화
tool_call_invocationtool_call_id, name, arguments에이전트가 도구를 호출한 기록
tool_call_resulttool_call_id, content도구 호출 결과
transcript는 민감 데이터 저장 금지 설정이나 통화 처리 상태에 따라 null일 수 있습니다.

​
call_analyzed

{
  "event": "call_analyzed",
  "call": {
    "call_id": "3079f46c-d141-4cd9-805f-69f212136b66",
    "agent": {
      "agent_id": "7ea3516d-08f6-4129-ab40-a731e379b320",
      "agent_version": "v3"
    },
    "call_type": "inbound",
    "from_number": "01012345678",
    "to_number": "07012345678",
    "dynamic_variables": {
      "customer_name": "홍길동"
    },
    "metadata": {
      "source": "crm"
    },
    "call_status": "ended",
    "disconnection_reason": "user_hangup",
    "start_at": 1741842354957,
    "end_at": 1741842393999,
    "transcript": [
      {
        "role": "agent",
        "content": "주문번호를 확인해드릴게요.",
        "start_at": 1741842358000,
        "end_at": 1741842361000
      },
      {
        "role": "tool_call_invocation",
        "tool_call_id": "tc_001",
        "name": "lookup_order",
        "arguments": {
          "order_id": "ORD-1234"
        }
      },
      {
        "role": "tool_call_result",
        "tool_call_id": "tc_001",
        "content": "{\"status\":\"shipped\",\"eta\":\"2026-04-30\"}"
      },
      {
        "role": "user",
        "content": "감사합니다.",
        "start_at": 1741842370000,
        "end_at": 1741842371200
      }
    ],
    "recording_url": "https://www.tryvox.co/api/store/download/...",
    "call_cost": {
      "total_cost": 12
    },
    "call_analysis": {
      "summary": "고객이 주문 배송 상태를 문의했고, 도착 예정일을 안내받았습니다.",
      "user_sentiment": "neutral",
      "custom_analysis_data": [
        { "name": "inquiry_type", "value": "배송 상태 문의" },
        { "name": "resolved", "value": true }
      ]
    },
    "opt_out_sensitive_data_storage": false
  }
}
필드타입설명
eventstring고정값 call_analyzed
call.call_idstring통화 ID
call.agent.agent_idstring에이전트 ID
call.agent.agent_versionstring에이전트 버전입니다.
call.call_typestring통화 유형
call.from_numberstring | null발신 번호
call.to_numberstring | null수신 번호
call.dynamic_variablesobject통화에 주입된 동적 변수
call.metadataobject통화 메타데이터
call.call_statusstring통화 상태입니다. 값은 ended, error, canceled, not_connected, queued, ongoing 중 하나입니다.
call.disconnection_reasonstring | null종료 사유
call.start_atnumber | null통화 시작 시각입니다. Unix 밀리초입니다.
call.end_atnumber | null통화 종료 시각입니다. Unix 밀리초입니다.
call.transcriptarray | null도구 호출을 포함한 스크립트입니다.
call.recording_urlstring | null녹음 파일 URL
call.call_costobject | null비용 정보입니다.
call.call_cost.total_costnumber | null통화 비용입니다.
call.call_analysisobject | null분석 결과입니다.
call.call_analysis.summarystring | null통화 요약
call.call_analysis.user_sentimentstring | null사용자 감정
call.call_analysis.custom_analysis_dataobject | array | null커스텀 분석 결과
call.opt_out_sensitive_data_storageboolean민감 데이터 저장 금지 여부

​
서버 구현 체크리스트

  • 같은 통화의 같은 이벤트가 다시 도착할 수 있습니다. 중복 저장을 방지하세요.
  • call_ended에서 비용이나 분석 필드를 기대하지 마세요.
  • 분석 결과 저장, 후속 자동화, 비용 집계는 call_analyzed에서 실행하세요.
  • 통화 결과는 call_status와 disconnection_reason을 함께 확인하세요.
  • 통화 시간은 end_at - start_at으로 계산하세요.

​
관련 문서

웹훅 스키마, webhook schema, call_analyzed, call_ended, mid_call, 웹훅 페이로드, webhook payload