웹훅 스키마

이 페이지는 v2 웹훅 페이로드를 기준으로 설명합니다. 이벤트마다 call, sms, campaign, sms_batch 본문 키가 다릅니다. 통화 종료와 분석 완료는 별도 이벤트로 전송됩니다.

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

공통 구조

카테고리	필드
envelope	`event`, `webhook_version`, 이벤트별 본문 키
전화번호	`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`)
캠페인	`campaign` (`campaign`)
대량 문자 배치	`sms_batch` (`sms_batch`)

통화 이벤트는 본문을 call 키에 담습니다. sms_received, campaign, sms_batch는 각각 sms, campaign, sms_batch 키에 담습니다. 자세한 내용은 sms_received를 참고하세요.웹훅 본문의 식별자는 call_id, campaign_id, batch_id처럼 리소스별 키를 씁니다. REST API 응답의 id와 키 이름이 다릅니다.

통화 이벤트

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

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

`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 형식은 없습니다. 서명 방식은 통화 데이터 웹훅과 동일합니다. 대시보드 설정 > 웹훅에서 수신 문자 웹훅 토글을 켜면 전송됩니다. 기본값은 꺼짐이고 켠 이후 수신분부터 전송됩니다.

대량 발신 이벤트

campaign과 sms_batch는 대시보드 설정 > 웹훅의 이벤트 구독에서 토글로 켭니다. 조직 설정 API의 webhook_event_subscriptions에 이벤트 값을 추가해도 됩니다.

이 두 이벤트도 워크스페이스 웹훅 URL과 같은 서명 방식을 따릅니다. 중복 처리는 서버 구현 체크리스트를 따르세요.

`campaign`

campaign은 대량 발신 캠페인이 success 또는 canceled로 종결될 때 전송됩니다. 캠페인을 시작, 일시정지, 재개할 때는 전송하지 않습니다. 웹훅은 캠페인 단위로 발행합니다. 재시도로 캠페인이 여러 개면 각각 전송합니다. 시트 전체의 완료 여부는 판정하지 않으므로 수신 서버에서 조합하세요.

{
  "event": "campaign",
  "webhook_version": "v2",
  "campaign": {
    "campaign_id": "018f3b2a-…",
    "name": "20260809_식봄_상암",
    "status": "success",
    "agent": {
      "agent_id": "…",
      "agent_version": "v3"
    },
    "from_number": "07012345678",
    "presentation_number": null,
    "total_calls": 100,
    "completed_calls": 97,
    "failed_calls": 3,
    "concurrency": 5,
    "active_concurrency": 0,
    "created_at": 1754700000000,
    "scheduled_at": null,
    "finished_at": 1754703600000,
    "paused_at": null,
    "paused_by": null,
    "call_time_window": { "…": "…" },
    "sheet_id": "018f3b29-…",
    "occurred_at": 1754703600000
  }
}

필드	타입	설명
`event`	string	고정값 `campaign`
`webhook_version`	string	고정값 `v2`
`campaign.campaign_id`	string	캠페인 ID
`campaign.name`	string	캠페인 이름
`campaign.status`	string	종결 상태입니다. 값은 `success`, `canceled` 중 하나입니다.
`campaign.agent`	object	캠페인에 사용한 에이전트 정보
`campaign.agent.agent_id`	string	에이전트 ID
`campaign.agent.agent_version`	string	에이전트 버전입니다. 값은 `current`, `production`, `v{n}` 형식입니다.
`campaign.from_number`	string	발신 번호
`campaign.presentation_number`	string \| null	발신표기번호
`campaign.total_calls`	number	전체 통화 수
`campaign.completed_calls`	number	완료된 통화 수
`campaign.failed_calls`	number	실패한 통화 수
`campaign.concurrency`	number	설정한 동시 통화 수
`campaign.active_concurrency`	number	종결 시점의 진행 중 통화 수
`campaign.created_at`	number	캠페인 생성 시각입니다. Unix 밀리초입니다.
`campaign.scheduled_at`	number \| null	예약 발신 시각입니다. Unix 밀리초입니다.
`campaign.finished_at`	number \| null	캠페인 종결 시각입니다. Unix 밀리초입니다.
`campaign.paused_at`	number \| null	마지막 일시정지 시각입니다. Unix 밀리초입니다.
`campaign.paused_by`	string \| null	마지막으로 캠페인을 일시정지한 사용자
`campaign.call_time_window`	object \| null	통화를 허용한 시간대 설정
`campaign.sheet_id`	string \| null	원본 시트 ID입니다. 시트를 거치지 않은 캠페인은 `null`입니다.
`campaign.occurred_at`	number	이벤트 발생 시각입니다. Unix 밀리초입니다.

campaign 본문은 캠페인 조회 API 응답 필드에 sheet_id와 occurred_at을 추가한 구조입니다.

`sms_batch`

sms_batch는 대량 문자 배치가 success 또는 fail로 종결될 때 전송됩니다. 발송이 시작되어 상태가 ongoing이 될 때는 전송하지 않습니다.

{
  "event": "sms_batch",
  "webhook_version": "v2",
  "sms_batch": {
    "batch_id": "018f3b2b-…",
    "title": "20260809_식봄_상암 부재문자",
    "status": "success",
    "total_count": 100,
    "success_count": 95,
    "failure_count": 3,
    "pending_count": 0,
    "blocked_count": 2,
    "created_at": 1754700000000,
    "finished_at": 1754703600000,
    "sheet_id": "018f3b29-…",
    "occurred_at": 1754703600000
  }
}

필드	타입	설명
`event`	string	고정값 `sms_batch`
`webhook_version`	string	고정값 `v2`
`sms_batch.batch_id`	string	대량 문자 배치 ID
`sms_batch.title`	string	대량 문자 배치 제목
`sms_batch.status`	string	종결 상태입니다. 값은 `success`, `fail` 중 하나입니다.
`sms_batch.total_count`	number	전체 수신자 수
`sms_batch.success_count`	number	발송 성공 수
`sms_batch.failure_count`	number	발송 실패 수
`sms_batch.pending_count`	number	발송 대기 수
`sms_batch.blocked_count`	number	차단된 수신자 수
`sms_batch.created_at`	number	배치 생성 시각입니다. Unix 밀리초입니다.
`sms_batch.finished_at`	number \| null	배치 종결 시각입니다. Unix 밀리초입니다.
`sms_batch.sheet_id`	string \| null	원본 시트 ID입니다. 시트를 거치지 않은 배치는 `null`입니다.
`sms_batch.occurred_at`	number	이벤트 발생 시각입니다. Unix 밀리초입니다.

sms_batch 본문은 대량 문자 배치 조회 API 응답에서 items를 제외하고, sheet_id와 occurred_at을 추가한 구조입니다.

서버 구현 체크리스트

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

시작하기

빌드하기

배포하기

모니터링

기타

공통 구조

통화 이벤트

`call_started`

`mid_call`

`call_ended`

녹음 파일 다운로드

스크립트 형식

`call_analyzed`

`sms_received`

첨부 파일 다운로드

대량 발신 이벤트

`campaign`

`sms_batch`

서버 구현 체크리스트

관련 문서

​공통 구조

​통화 이벤트

​call_started

​mid_call

​call_ended

​녹음 파일 다운로드

​스크립트 형식

​call_analyzed

​sms_received

​첨부 파일 다운로드

​대량 발신 이벤트

​campaign

​sms_batch

​서버 구현 체크리스트

​관련 문서

공통 구조

통화 이벤트

`call_started`

`mid_call`

`call_ended`

녹음 파일 다운로드

스크립트 형식

`call_analyzed`

`sms_received`

첨부 파일 다운로드

대량 발신 이벤트

`campaign`

`sms_batch`

서버 구현 체크리스트

관련 문서