웹훅 스키마

개요

이 페이지는 v2 통화 데이터 웹훅을 기준으로 설명합니다. 모든 v2 이벤트는 { "event", "webhook_version", "call" } 구조를 사용합니다. 통화 종료와 분석 완료는 별도 이벤트로 전송됩니다.

비용과 분석 결과는 call_analyzed에서 확인하세요. call_ended에는 포함되지 않습니다.

이벤트 생명주기

통화 데이터 웹훅은 통화 진행 상태와 분석 완료 상태를 나누어 전달합니다.

call_analyzed는 통화 종료 후 비동기로 도착할 수 있습니다. call_ended에서 비용, 분석 결과, duration_ms를 기대하지 마세요.

공통 구조

카테고리	필드
envelope	`event`, `webhook_version`, `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 키에 담습니다. 단, sms_received는 예외로 본문을 sms 키에 담습니다. 자세한 내용은 sms_received를 참고하세요.

`call_started`

{
  "event": "call_started",
  "webhook_version": "v2",
  "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
  }
}

필드	타입	설명
`event`	string	고정값 `call_started`
`webhook_version`	string	고정값 `v2`
`call.call_id`	string	통화 ID
`call.agent.agent_id`	string	에이전트 ID
`call.agent.agent_version`	string	에이전트 버전입니다. 예: `current`, `v3`
`call.call_type`	string	통화 유형
`call.from_number`	string \| null	발신 번호
`call.to_number`	string \| null	수신 번호
`call.dynamic_variables`	object	통화에 주입된 동적 변수
`call.metadata`	object	통화 메타데이터
`call.start_at`	number \| null	통화 시작 시각입니다. Unix 밀리초입니다.
`call.opt_out_sensitive_data_storage`	boolean	통화 데이터 저장 제외 여부

`mid_call`

{
  "event": "mid_call",
  "webhook_version": "v2",
  "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": "주문한 제품이 언제 도착하나요?"
    }
  }
}

필드	타입	설명
`event`	string	고정값 `mid_call`
`webhook_version`	string	고정값 `v2`
`call.call_id`	string	통화 ID
`call.agent.agent_id`	string	에이전트 ID
`call.agent.agent_version`	string	에이전트 버전입니다.
`call.occurred_at`	number	이벤트 발생 시각입니다. Unix 밀리초입니다.
`call.event_type`	string	세부 이벤트 유형입니다.
`call.event_data`	object	세부 이벤트 데이터입니다.

`call_ended`

{
  "event": "call_ended",
  "webhook_version": "v2",
  "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
  }
}

필드	타입	설명
`event`	string	고정값 `call_ended`
`webhook_version`	string	고정값 `v2`
`call.call_id`	string	통화 ID
`call.agent.agent_id`	string	에이전트 ID
`call.agent.agent_version`	string	에이전트 버전입니다.
`call.call_type`	string	통화 유형
`call.from_number`	string \| null	발신 번호
`call.to_number`	string \| null	수신 번호
`call.dynamic_variables`	object	통화에 주입된 동적 변수
`call.metadata`	object	통화 메타데이터
`call.call_status`	string	통화 상태입니다. 값은 `ended`, `error`, `canceled`, `not_connected`, `queued`, `ongoing` 중 하나입니다.
`call.disconnection_reason`	string \| null	종료 사유
`call.start_at`	number \| null	통화 시작 시각입니다. Unix 밀리초입니다.
`call.end_at`	number \| null	통화 종료 시각입니다. Unix 밀리초입니다.
`call.transcript`	array \| null	도구 호출을 포함한 스크립트입니다.
`call.recording_url`	string \| null	녹음 파일 URL
`call.opt_out_sensitive_data_storage`	boolean	통화 데이터 저장 제외 여부

call_ended에는 비용, 분석 결과, duration_ms가 포함되지 않습니다. 통화 시간은 end_at - start_at으로 계산하세요. 비용과 분석 결과는 call_analyzed에서 확인하세요.

녹음 파일 다운로드

recording_url은 인증이 필요한 엔드포인트입니다. API 키로 녹음을 내려받는 방법과 파일 형식(스테레오 OGG, 채널 분리)은 통화 녹음에서 확인하세요.

스크립트 형식

transcript는 발화와 도구 호출 기록을 한 배열에 담습니다. 도구를 사용하지 않은 통화에는 agent와 user 항목만 포함될 수 있습니다.

`role`	주요 필드	설명
`agent`	`content`, `start_at`, `end_at`	에이전트 발화
`user`	`content`, `start_at`, `end_at`	사용자 발화
`tool_call_invocation`	`tool_call_id`, `name`, `arguments`	에이전트가 도구를 호출한 기록
`tool_call_result`	`tool_call_id`, `content`	도구 호출 결과

transcript는 통화 데이터 저장 제외 설정이나 통화 처리 상태에 따라 null일 수 있습니다.

`call_analyzed`

{
  "event": "call_analyzed",
  "webhook_version": "v2",
  "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
  }
}

필드	타입	설명
`event`	string	고정값 `call_analyzed`
`webhook_version`	string	고정값 `v2`
`call.call_id`	string	통화 ID
`call.agent.agent_id`	string	에이전트 ID
`call.agent.agent_version`	string	에이전트 버전입니다.
`call.call_type`	string	통화 유형
`call.from_number`	string \| null	발신 번호
`call.to_number`	string \| null	수신 번호
`call.dynamic_variables`	object	통화에 주입된 동적 변수
`call.metadata`	object	통화 메타데이터
`call.call_status`	string	통화 상태입니다. 값은 `ended`, `error`, `canceled`, `not_connected`, `queued`, `ongoing` 중 하나입니다.
`call.disconnection_reason`	string \| null	종료 사유
`call.start_at`	number \| null	통화 시작 시각입니다. Unix 밀리초입니다.
`call.end_at`	number \| null	통화 종료 시각입니다. Unix 밀리초입니다.
`call.transcript`	array \| null	도구 호출을 포함한 스크립트입니다.
`call.recording_url`	string \| null	녹음 파일 URL
`call.call_cost`	object \| null	비용 정보입니다.
`call.call_cost.total_cost`	number \| null	통화 비용입니다.
`call.call_analysis`	object \| null	분석 결과입니다.
`call.call_analysis.summary`	string \| null	통화 요약
`call.call_analysis.user_sentiment`	string \| null	사용자 감정
`call.call_analysis.custom_analysis_data`	object \| array \| null	커스텀 분석 결과
`call.opt_out_sensitive_data_storage`	boolean	통화 데이터 저장 제외 여부

`sms_received`

sms_received는 워크스페이스 번호로 문자(SMS/MMS)를 수신할 때 전송됩니다. 워크스페이스 웹훅 전용이며 opt-in 설정을 켠 워크스페이스에만 전송됩니다. 본문 키는 통화 이벤트와 달리 call이 아니라 sms입니다.

{
  "event": "sms_received",
  "webhook_version": "v2",
  "sms": {
    "mseq": 12345,
    "from_number": "01012345678",
    "to_number": "07012345678",
    "text": "문의드립니다",
    "received_at": 1765432100000,
    "call_id": null,
    "chat_id": null,
    "attachments": [
      { "file_key": "file_AbC123", "mime_type": "image/jpeg" }
    ]
  }
}

필드	타입	설명
`event`	string	고정값 `sms_received`
`webhook_version`	string	고정값 `v2`
`sms.mseq`	number	수신 문자의 고유 식별자
`sms.from_number`	string \| null	발신 번호
`sms.to_number`	string \| null	문자를 수신한 워크스페이스 번호
`sms.text`	string \| null	문자 본문
`sms.received_at`	number \| null	수신 시각입니다. Unix 밀리초입니다.
`sms.call_id`	string \| null	통화 중 수신된 문자면 해당 통화 ID
`sms.chat_id`	string \| null	양방향 문자 대화에 속하면 해당 대화 ID
`sms.attachments`	array	MMS 이미지 첨부 목록입니다. 첨부가 없으면 빈 배열입니다.
`sms.attachments[].file_key`	string	첨부 파일 식별자
`sms.attachments[].mime_type`	string	첨부 파일 MIME 타입

첨부 파일 다운로드

file_key로 첨부 파일 원본을 받으려면 파일 다운로드 API를 호출하세요.

cURL

curl --request GET \
  --url https://client-api.tryvox.co/v3/files/{file_key}/content \
  --header 'Authorization: Bearer <token>' \
  --output attachment.jpg

응답 본문이 파일 원본입니다. Content-Type은 저장된 MIME 타입(image/jpeg, image/png, image/gif)을 그대로 따릅니다. 같은 워크스페이스가 소유한 file_key만 받을 수 있습니다. 전체 파라미터는 v3 API 참조의 파일 > 파일 다운로드에서 확인하세요.

본문 키가 call이 아니라 sms입니다. event 키로 분기하는 핸들러는 수정 없이 동작합니다. call 키를 무조건 읽는 핸들러는 sms_received를 별도로 분기하세요.

sms_received는 항상 v2 형식으로 전송됩니다. v1 형식은 없습니다. 서명 방식은 통화 데이터 웹훅과 동일합니다. 대시보드 설정 > 웹훅에서 수신 문자 웹훅 토글을 켜면 전송됩니다. 기본값은 꺼짐이고 켠 이후 수신분부터 전송됩니다.

서버 구현 체크리스트

같은 통화의 같은 이벤트가 다시 도착할 수 있습니다. 중복 저장을 방지하세요.
v2 수신 스키마에는 최상위 webhook_version 필드를 포함하세요.
call_ended에서 비용이나 분석 필드를 기대하지 마세요.
분석 결과 저장, 후속 자동화, 비용 집계는 call_analyzed에서 실행하세요.
통화 결과는 call_status와 disconnection_reason을 함께 확인하세요.
통화 시간은 end_at - start_at으로 계산하세요.
sms_received는 본문 키가 sms이므로 call 키를 무조건 읽는 핸들러는 별도로 분기하세요.

시작하기

빌드하기

배포하기

모니터링

기타

개요

이벤트 생명주기

공통 구조

`call_started`

`mid_call`

`call_ended`

녹음 파일 다운로드

스크립트 형식

`call_analyzed`

`sms_received`

첨부 파일 다운로드

서버 구현 체크리스트

관련 문서

​개요

​이벤트 생명주기

​공통 구조

​call_started

​mid_call

​call_ended

​녹음 파일 다운로드

​스크립트 형식

​call_analyzed

​sms_received

​첨부 파일 다운로드

​서버 구현 체크리스트

​관련 문서

개요

이벤트 생명주기

공통 구조

`call_started`

`mid_call`

`call_ended`

녹음 파일 다운로드

스크립트 형식

`call_analyzed`

`sms_received`

첨부 파일 다운로드

서버 구현 체크리스트

관련 문서