웹훅 스키마

이벤트별 페이로드 필드와 예시예요. 본문 키는 이벤트마다 call, operator_call, sms, campaign, sms_batch로 달라요. 본문 식별자는 call_id, operator_call_id, campaign_id, batch_id처럼 리소스별 키를 써서 REST API 응답의 id와 이름이 달라요. 비용과 분석 결과는 call_ended가 아니라 call_analyzed에서 받으세요.

통화 이벤트

통화 데이터 웹훅은 통화 진행 상태와 분석 완료 상태를 나눠 보내요. call_started, mid_call, call_ended가 통화 중에 오고, call_analyzed는 통화가 끝난 뒤 비동기로 와요. 통화 중에 맥락을 넣으면 요청마다 그 결과로 call_context도 와요. 통화 유형마다 오는 순서와 시점은 이벤트 라이프사이클에 있어요.

`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`

AI 통화 중 플로우 전환이나 발화가 생기면 와요. 상담사에게 전환된 뒤의 발화는 상담사 구간의 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_context`

통화 중 맥락 넣기로 넣은 맥락의 결과가 정해지면 요청마다 한 번 와요. 통화 데이터 웹훅 URL이 있으면 따로 구독하지 않아도 와요. 맥락 본문은 담기지 않아요.

{
  "event": "call_context",
  "webhook_version": "v2",
  "call": {
    "call_id": "3079f46c-d141-4cd9-805f-69f212136b66",
    "agent": {
      "agent_id": "7ea3516d-08f6-4129-ab40-a731e379b320",
      "agent_version": "v3"
    },
    "control_id": "f5d53050afebe51cfe78217380fbf33c19720608c8e3e790065a6f253301041f",
    "idempotency_key": "context-request-001",
    "metadata": {
      "source": "crm"
    },
    "response": "interrupt_agent",
    "input": "applied",
    "consumed": true,
    "reply": "completed",
    "failure_reason": null,
    "received_at": 1742158401000,
    "consumed_at": 1742158401200,
    "reply_started_at": 1742158402100,
    "settled_at": 1742158405800
  }
}

필드	타입	설명
`event`	string	고정값 `call_context`
`webhook_version`	string	고정값 `v2`
`call.call_id`	string	통화 ID
`call.agent.agent_id`	string	에이전트 ID
`call.agent.agent_version`	string	에이전트 버전. 게시한 버전은 `v3`처럼, 게시 전 설정으로 진행한 통화는 `current`
`call.control_id`	string	맥락 넣기 API 응답의 `control_id`. 요청과 짝을 맞출 때 써요
`call.idempotency_key`	string	요청에 쓴 `Idempotency-Key`
`call.metadata`	object	통화 메타데이터
`call.response`	string	요청한 응답 방식. `none`, `when_idle`, `interrupt_agent`
`call.input`	string \| null	맥락이 에이전트에 닿은 결과. `applied`, `rejected`, `canceled`
`call.consumed`	boolean	에이전트가 이 맥락을 넣고 응답을 만들기 시작했는지 여부. 맥락에 대해 말했다는 뜻은 아니에요
`call.reply`	string	에이전트가 맥락에 대해 말한 결과. 값은 아래 목록에 있어요
`call.failure_reason`	string \| null	반영하지 못했거나 말하지 못한 사유
`call.received_at`	number \| null	통화가 맥락을 받은 시각(Unix 밀리초)
`call.consumed_at`	number \| null	에이전트가 맥락을 넣고 응답을 만들기 시작한 시각(Unix 밀리초)
`call.reply_started_at`	number \| null	맥락에 대해 말하기 시작한 시각(Unix 밀리초)
`call.settled_at`	number \| null	결과가 정해진 시각(Unix 밀리초)

reply 값은 아래와 같아요. 웹훅은 결과가 정해진 뒤에 오므로 진행 중 값은 오지 않아요.

not_requested: response가 none이라 말하기를 요청하지 않았어요.
completed: 맥락에 대해 끝까지 말했어요.
interrupted: 말하다 끊겼어요. 다시 말하지 않지만 맥락은 이후 응답에 남아요.
merged: 따로 말하지 않고, 이 맥락이 담긴 일반 응답이 끝까지 재생됐어요. interrupt_agent 요청이 고객이 말하는 중에 도착하면 그 말에 대한 응답에 합쳐져 이 값으로 끝나요.
expired: expires_in_seconds 안에 말을 시작하지 못했어요.
canceled: 상담사 전환, 상담사 통화, 통화 종료 때문에 말하지 않았어요.
unknown: 결과를 남기기 전에 처리가 중단돼 알 수 없어요.

failure_reason 값은 아래와 같아요.

transfer_in_progress: 상담사 전환 중이에요.
operator_active: 상담사가 통화를 맡고 있어요.
call_ending: 통화가 끝나는 중이에요.
deadline: 기한이 지났어요.
limit_exceeded: 통화 하나의 맥락 한도를 넘었어요.
session_unavailable: 통화가 맥락을 받을 수 없는 상태였어요.
worker_lost: 처리가 중단돼 결과를 남기지 못했어요.

아직 값이 없는 상태나 시각은 필드를 빼지 않고 null로 보내요. none 요청은 반영되는 즉시 결과가 정해져 consumed가 보통 false이고, 그 뒤 응답에 쓰여도 웹훅을 다시 보내지 않아요. 웹훅 버전이 v1이면 webhook_version이 없고, call 대신 call_context 키에 같은 필드가 담겨요. agent 객체 대신 agent_id가 그 안에 와요.

`call_ended`

개인정보 마스킹을 켜면 종료 이벤트가 가리기 전에 와서 call.transcript가 비어 있을 수 있어요. 아래 예시는 마스킹을 끈 경우예요.

{
  "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\"}",
        "success": true,
        "status_code": 200
      },
      {
        "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.scrubbed_recording_url`	string \| null	개인정보를 가린 녹음 파일 URL이에요. 파일이 없으면 `null`이에요.
`call.opt_out_sensitive_data_storage`	boolean	통화 데이터 저장 제외 여부

통화 시간은 end_at - start_at으로 계산하세요. recording_url은 인증이 필요한 엔드포인트예요. API 키로 녹음을 내려받는 방법과 스테레오 OGG 채널 분리 형식은 통화 녹음에 있어요.

스크립트 형식

transcript는 발화와 도구 호출 기록을 한 배열에 담아요. 도구를 쓰지 않은 통화에는 agent와 user 항목만 들어가요. 통화 데이터 저장 제외 설정이나 통화 처리 상태에 따라 null일 수 있어요.

`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`, `success`, `status_code`	도구 호출 결과

도구 호출 결과에는 아래 두 필드가 함께 들어가요. 개인정보를 가린 결과에도 똑같이 들어 있어요.

필드	타입	설명
`success`	boolean	도구 실행 중 오류가 기록됐거나 도구가 실패로 기록되면 `false`예요. 오류 메시지가 비어 있어도 `false`예요. 그 밖에는 `true`이고, 성공 여부를 따로 저장하지 않은 예전 기록도 `true`예요.
`status_code`	integer \| null	저장된 도구 응답 상태 코드예요. 저장된 값이 없으면 `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\"}",
        "success": true,
        "status_code": 200
      },
      {
        "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": [
        { "type": "string", "name": "inquiry_type", "value": "배송 상태 문의" },
        { "type": "boolean", "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.scrubbed_recording_url`	string \| null	개인정보를 가린 녹음 파일 URL이에요. 파일이 없으면 `null`이에요.
`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	커스텀 분석 결과예요. 항목마다 `type`, `name`, `value`가 있어요.
`call.opt_out_sensitive_data_storage`	boolean	통화 데이터 저장 제외 여부

상담사 통화 이벤트

AI 통화에서 상담사에게 전환된 뒤의 이벤트예요. 안내 후 전환과 상담사 이어받기에 적용되고, 통화 데이터 웹훅 URL을 설정하면 따로 구독하지 않아도 와요.

이벤트	오는 때	본문 키
`operator_call_started`	고객과 상담사가 연결됐을 때	`operator_call`
`mid_call`	상담사 구간에서 고객이나 상담사의 발화가 확정됐을 때	`call`
`operator_call_ended`	상담사 통화가 끝났을 때	`operator_call`

오는 순서는 안내 후 전환 라이프사이클에 있어요.

`operator_call_started`

{
  "event": "operator_call_started",
  "webhook_version": "v2",
  "operator_call": {
    "operator_call_id": "6b84f835-1af3-472d-bb25-3377c9792af9",
    "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"
    },
    "operator": {
      "member_id": "54ddfd7a-1c4f-4a24-812f-67aa43e4f521",
      "name": "김상담",
      "external_id": "operator-42"
    },
    "mode": "warm",
    "source": "handoff",
    "handoff_id": "0b29c8f2-9765-4c64-b10a-4987dfc077dd",
    "occurred_at": 1756268004000
  }
}

`mid_call`

고객이나 상담사의 발화가 확정되면 와요. AI 구간과 같은 mid_call 이벤트이고, call.operator_call_id로 구분해요.

{
  "event": "mid_call",
  "webhook_version": "v2",
  "call": {
    "call_id": "3079f46c-d141-4cd9-805f-69f212136b66",
    "operator_call_id": "6b84f835-1af3-472d-bb25-3377c9792af9",
    "agent": {
      "agent_id": "7ea3516d-08f6-4129-ab40-a731e379b320",
      "agent_version": "v3"
    },
    "occurred_at": 1756268104000,
    "event_type": "call_message",
    "event_data": {
      "role": "operator",
      "content": "네, 바로 확인해 드리겠습니다."
    }
  }
}

필드	타입	설명
`event`	string	고정값 `mid_call`
`webhook_version`	string	고정값 `v2`
`call.call_id`	string	선행 AI 통화 ID
`call.operator_call_id`	string	상담사 통화 ID예요. `operator_call_started`, `operator_call_ended`의 ID와 같아요. AI 구간에는 이 키가 없어요.
`call.agent`	object	선행 AI 통화의 에이전트 정보
`call.agent.agent_id`	string	에이전트 ID
`call.agent.agent_version`	string	에이전트 버전
`call.occurred_at`	number	이벤트 발생 시각(Unix 밀리초)
`call.event_type`	string	고정값 `call_message`
`call.event_data`	object	세부 이벤트 데이터
`call.event_data.role`	string	고객은 `user`, 상담사는 `operator`예요.
`call.event_data.content`	string	확정된 발화 내용

`operator_call_ended`

{
  "event": "operator_call_ended",
  "webhook_version": "v2",
  "operator_call": {
    "operator_call_id": "6b84f835-1af3-472d-bb25-3377c9792af9",
    "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"
    },
    "operator": {
      "member_id": "54ddfd7a-1c4f-4a24-812f-67aa43e4f521",
      "name": "김상담",
      "external_id": "operator-42"
    },
    "mode": "warm",
    "source": "handoff",
    "handoff_id": "0b29c8f2-9765-4c64-b10a-4987dfc077dd",
    "status": "ended",
    "disconnection_reason": "operator_hangup",
    "start_at": 1756268004000,
    "end_at": 1756268204000,
    "recording_url": "https://www.tryvox.co/api/store/download/...",
    "occurred_at": 1756268204000
  }
}

시작 이벤트에는 start_at이 없고, occurred_at이 상담사 통화 조회 응답의 start_at과 같아요. 종료 이벤트의 occurred_at은 end_at과 같아요.

필드	타입	설명
`event`	string	`operator_call_started` 또는 `operator_call_ended`
`webhook_version`	string	고정값 `v2`
`operator_call.operator_call_id`	string	상담사 통화 ID예요. v3 API 참조의 상담사 통화 > 상담사 통화 목록 조회 응답의 `id`와 같은 값이에요.
`operator_call.call_id`	string \| null	선행 AI 통화 ID
`operator_call.agent`	object \| null	선행 AI 통화의 에이전트 정보
`operator_call.agent.agent_id`	string	에이전트 ID예요. `agent` 객체가 있으면 늘 들어 있고 null이 아니에요.
`operator_call.agent.agent_version`	string	에이전트 버전이에요. 값은 `current`, `production`, `v{n}` 꼴이에요. `agent` 객체가 있으면 늘 들어 있고 null이 아니에요. 통화 이벤트의 `agent.agent_version`은 `current`와 `v{n}`만 쓰지만, 상담사 통화 이벤트에는 `production`도 올 수 있어요.
`operator_call.call_type`	string	상담사 기준 통화 시작 방향이에요. AI 통화를 이어받으면 `inbound`예요. 고객 통화의 전화 방향은 선행 AI 통화의 `call_type`을 보세요.
`operator_call.from_number`	string \| null	발신번호
`operator_call.to_number`	string \| null	수신번호
`operator_call.dynamic_variables`	object	선행 AI 통화에 주입된 동적 변수
`operator_call.metadata`	object	선행 AI 통화의 메타데이터
`operator_call.operator`	object	상담사 정보
`operator_call.operator.member_id`	string \| null	워크스페이스 멤버 ID
`operator_call.operator.name`	string \| null	상담사 표시 이름
`operator_call.operator.external_id`	string \| null	외부 시스템의 상담사 ID
`operator_call.mode`	string \| null	상담사 연결 방식이에요. AI 통화에서 전환됐으면 `warm`이에요.
`operator_call.source`	string \| null	연결 경로예요. 상담사가 직접 이어받으면 `operator`, 인계 요청을 수락하면 `handoff`, 그 밖의 안내 후 전환에서는 `null`이에요.
`operator_call.handoff_id`	string \| null	상담사 인계 ID예요. 인계를 수락했으면 상담사 인계 ID이고, 나머지 경로는 `null`이에요.
`operator_call.status`	string	상담사 통화의 최종 상태예요. 값은 `ended`, `failed` 가운데 하나이고 종료 이벤트에만 들어 있어요.
`operator_call.disconnection_reason`	string	종료 사유예요. 종료 이벤트에 늘 들어 있고 null이 아니에요. 값은 `operator_hangup`, `user_hangup`, `dial_failed`, `dial_no_answer`, `dial_busy`, `orphaned_no_agent_pickup`, `error_voxai`, `system_hangup` 가운데 하나이고, REST 상담사 통화 조회와 같은 전용 어휘를 써요.
`operator_call.start_at`	number \| null	상담사 통화 시작 시각이에요. 종료 이벤트에 들어 있어요.
`operator_call.end_at`	number	상담사 통화 종료 시각이에요. 종료 이벤트에만 들어 있어요.
`operator_call.recording_url`	string \| null	상담사 통화의 녹음 파일 URL이에요. 종료 이벤트에만 들어 있어요. 녹음을 저장하지 않거나 보내는 시점에 파일이 준비되지 않았으면 `null`이에요.
`operator_call.occurred_at`	number	이벤트 발생 시각이고 Unix 밀리초예요. 시작 이벤트에서는 상담사 통화 조회 응답의 `start_at`과 같고, 종료 이벤트에서는 `end_at`과 같아요.

종료 이벤트의 recording_url은 만료되지 않아요. dynamic_variables, metadata, mode, source, handoff_id는 이벤트가 생긴 통화와 연결 경로를 설명하는 웹훅 전용 컨텍스트라, v3 API 참조의 상담사 통화 > 상담사 통화 조회 응답에는 들어 있지 않아요.

문서에 없던 takeover 이벤트를 받고 있었다면 이 두 이벤트로 바뀌어요. 본문 키는 operator_call이고 takeover_id, takeover_event_type, message_count, duration_ms는 없어요.

상담사 통화 상세 조회

대화록, 비용, 종료 이벤트에 없는 녹음 URL이 필요하면 v3 API 참조의 상담사 통화 > 상담사 통화 조회를 호출하세요.

cURL

curl --request GET \
  --url https://client-api.tryvox.co/v3/operator-calls/{operator_call_id} \
  --header 'Authorization: Bearer <token>'

단건 응답의 recording_url은 15분 뒤 만료되는 서명 URL이에요. URL을 저장해 두지 말고 재생할 때 다시 조회하세요. 일부 과거 통화는 만료가 없는 다운로드 URL로 올 수 있어요. 상담사 통화 조회는 통화 조회와 같은 워크스페이스 요청 한도를 함께 써요. 주기적으로 폴링하지 말고 웹훅을 받은 뒤 필요한 통화만 조회하세요.

전달 보장과 재시도

수신 서버가 응답을 돌려주면 상태 코드와 상관없이 그 시도는 끝나요. 4xx나 5xx로 재시도를 이끌어 낼 수 없어요. vox.ai는 요청마다 5초를 기다려요. 5초 안에 수신 서버와 연결되지 않을 때만 곧바로 한 번 더 보내요. 연결된 뒤 5초 안에 응답이 없거나, 연결이 거부되거나 끊기면 같은 이벤트를 다시 보내지 않아요. 같은 이벤트를 한 번만 처리하려면 다음 키를 쓰세요. 통화 이벤트는 (event, call_id), 상담사 통화 이벤트는 (event, operator_call_id)예요. call_context는 한 통화에서 요청마다 하나씩 오므로 (event, call_id, control_id)로 거르세요. mid_call은 AI 구간에서 call_id, 상담사 구간에서 operator_call_id를 쓰고, 여기에 event, occurred_at, event_type, event_data를 더해 키를 만드세요.

요청을 먼저 저장하고 5초 안에 2xx를 돌려준 뒤 후속 처리는 비동기로 실행하세요. 5초를 넘긴 이벤트는 다시 오지 않으니, 놓친 내용은 v3 API로 그 통화를 다시 조회해 채우세요.

sms_received

번호 상세에서 문자 수신을 신청하고 승인받은 뒤 쓰세요. sms_received는 워크스페이스 번호로 SMS나 MMS를 받을 때 와요. 워크스페이스 웹훅 전용이고, 설정 > 웹훅의 이벤트 구독에서 수신 문자를 켜고 저장한 워크스페이스에만 와요. 기본값은 꺼짐이고, 켠 뒤 받은 문자부터 와요. 서명 방식은 통화 데이터 웹훅과 같아요. 본문 키는 통화 이벤트와 달리 call이 아니라 sms예요. event 키로 분기하는 핸들러는 고치지 않아도 되지만, call 키를 무조건 읽는 핸들러는 sms_received를 따로 분기하세요.

{
  "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은 image/jpeg, image/png, image/gif 가운데 저장된 MIME 타입을 그대로 따라요. 같은 워크스페이스가 가진 file_key만 받을 수 있어요. 전체 파라미터는 v3 API 참조의 파일 > 파일 다운로드에 있어요.

sms_sent

sms_sent는 발신한 문자가 sent, failed, blocked, canceled 가운데 하나로 끝났을 때 문자마다 한 번 와요. API, 대시보드, 에이전트의 문자 발신 도구, 대량 문자 발신 어느 경로로 보낸 문자든 같아요. 대량 발신의 문자는 한 건씩 오고, 대량 발신 전체 결과는 sms_batch로 와요. 이벤트는 통신사의 최종 결과가 나올 때 와요. 보통 발신하고 몇 초 안에 도착하고, 수신 휴대폰이 꺼져 있으면 최대 24시간이 걸려요. 24시간 안에 결과를 받지 못하면 failed(SMS_NO_RESULT)로 와요. 워크스페이스 웹훅 전용이고, 설정 > 웹훅의 이벤트 구독에서 문자 발신 결과를 켜고 저장한 워크스페이스에만 와요. 기본값은 꺼짐이고, 켠 뒤 끝난 문자부터 와요. 서명 방식은 통화 데이터 웹훅과 같아요. 본문 키는 sms_received처럼 sms예요.

{
  "event": "sms_sent",
  "webhook_version": "v2",
  "sms": {
    "sms_message_id": "a3f9c01b7d42",
    "from_number": "07012345678",
    "to_number": "01012345678",
    "message": "[vox] 내일 오후 2시 방문 예약이 확정됐습니다.",
    "title": null,
    "message_type": "sms",
    "byte_count": 45,
    "image_urls": null,
    "call_id": null,
    "chat_id": null,
    "customer_id": null,
    "batch_id": "018f3b2b-…",
    "metadata": { "row_id": "12" },
    "status": "sent",
    "error": null,
    "created_at": 1754700000000,
    "delivered_at": 1754700004000,
    "occurred_at": 1754700005000
  }
}

필드	타입	설명
`event`	string	고정값 `sms_sent`
`webhook_version`	string	고정값 `v2`
`sms.sms_message_id`	string	발신 문자의 고유 식별자
`sms.from_number`	string	발신번호
`sms.to_number`	string \| null	수신번호예요. 보존 기간이 지나 지운 번호는 `null`이에요.
`sms.message`	string	문자 본문
`sms.title`	string \| null	문자 제목이에요. 없으면 `null`이에요.
`sms.message_type`	string	문자 유형이에요. 값은 `sms`, `lms`, `mms` 가운데 하나예요.
`sms.byte_count`	number	본문 바이트 수예요. 새로 보낸 문자는 EUC-KR 기준이에요.
`sms.image_urls`	array \| null	MMS에 첨부한 이미지 URL이에요. 텍스트만 보냈으면 `null`이에요.
`sms.call_id`	string \| null	통화에 귀속된 문자면 해당 통화 ID
`sms.chat_id`	string \| null	채팅에 귀속된 문자면 해당 채팅 ID
`sms.customer_id`	string \| null	상대방 전화번호로 귀속한 고객 ID예요. 아직 귀속되지 않았으면 `null`이에요.
`sms.batch_id`	string \| null	대량 문자 발신으로 보낸 문자면 해당 대량 발신 ID예요. 아니면 `null`이에요.
`sms.metadata`	object \| null	발신 요청에 담은 메타데이터예요. 없으면 `null`이에요.
`sms.status`	string	끝난 상태예요. 값은 `sent`(성공, 요금 부과), `failed`(실패), `blocked`(제한된 내용이 있어 보내지 않음), `canceled`(대량 발신 취소로 보내지 않음) 가운데 하나예요. `sent`는 단말 수신이나 열람을 보장하지 않아요.
`sms.error`	object \| null	`failed`, `blocked`, `canceled`일 때의 사유예요. `sent`면 `null`이에요.
`sms.error.code`	string	오류 코드예요. 값은 아래 표를 보세요.
`sms.error.message`	string	사람이 읽는 사유
`sms.created_at`	number	문자를 만든 시각(Unix 밀리초)
`sms.delivered_at`	number \| null	수신 휴대폰에 전달된 시각(Unix 밀리초)이에요. `sent`일 때만 값이 있고, 전달 시각을 알 수 없으면 `null`이에요.
`sms.occurred_at`	number	문자가 끝난 시각(Unix 밀리초)

sms 본문은 발신 문자 조회 API 응답에서 id를 sms_message_id로 바꾸고 occurred_at을 더한 구조예요. sms.error의 코드와 메시지는 다음과 같아요.

코드	메시지
`SMS_INVALID_RECIPIENT`	`없거나 사용이 정지된 번호입니다.`
`SMS_RECIPIENT_UNREACHABLE`	`수신 휴대폰이 꺼져 있거나 받을 수 없는 상태입니다.`
`SMS_SPAM_BLOCKED`	`통신사가 스팸으로 차단했습니다.`
`SMS_SENDER_NUMBER_REJECTED`	`발신번호가 통신사 기준에 맞지 않습니다.`
`SMS_DELIVERY_UNCONFIRMED`	`전달 여부를 확인할 수 없습니다.`
`SMS_NO_RESULT`	`24시간 안에 결과를 받지 못했습니다.`
`SMS_SEND_FAILED`	`문자 발신에 실패했습니다.`
`SMS_CONTENT_BLOCKED`	`보낼 수 없는 내용이 포함되어 있습니다.`
`BILLING_SUSPENDED`	`미납으로 서비스 이용이 정지되었습니다.`
`BLOCKED_NUMBER`	`광고 문자 수신을 거부한 번호입니다.`
`SMS_BLOCKED`	`발신이 제한되어 보내지 않았습니다.`
`SMS_CANCELED`	`대량 문자 발신이 취소되어 보내지 않았습니다.`

SMS_CONTENT_BLOCKED, BILLING_SUSPENDED, BLOCKED_NUMBER, SMS_BLOCKED는 blocked, SMS_CANCELED는 canceled일 때 와요. 접수 단계의 검증에 걸려 failed가 된 문자는 FILE_NOT_FOUND처럼 그 검증의 코드와 메시지를 그대로 쓰고, 구체적인 사유가 없는 그 밖의 실패는 SMS_SEND_FAILED예요.

대량 발신 이벤트

campaign과 sms_batch를 받으려면 대시보드 설정 > 웹훅의 이벤트 구독에서 대량 발신 종결과 대량 문자 발신 종결을 켜고 저장하세요. 워크스페이스 설정 API의 webhook_event_subscriptions에 이벤트 값을 더해도 돼요. 두 이벤트도 워크스페이스 웹훅과 같은 서명 방식을 따르고, 중복 처리는 전달 보장과 재시도를 따르세요.

`campaign`

campaign은 대량 발신이 success나 canceled로 종결될 때 와요. 대량 발신을 시작, 일시정지, 재개할 때는 오지 않아요. 웹훅은 대량 발신 단위로 와요. 자동 재시도를 켠 대량 발신은 실패분을 다시 걸 때 새 건이 만들어지므로 종결 웹훅도 원본과 재시도분이 따로 와요. 재시도 건의 sheet_id는 원본과 같아요. 시트 전체가 끝났는지는 판정하지 않으니 수신 서버에서 모아 판단하세요.

{
  "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, canceled로 종결될 때 와요. 발신이 시작되어 상태가 ongoing이 될 때나 일시정지, 재개할 때는 오지 않아요. 문자별 결과가 필요하면 sms_sent를 함께 구독하세요. 모든 문자를 보낸 뒤에도 통신사 결과를 기다리는 동안은 ongoing이에요. 모든 결과가 나오거나 마지막 문자를 발신하고 10분이 지나면 종결하고, 이벤트는 그때 한 번 와요.

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

필드	타입	설명
`event`	string	고정값 `sms_batch`
`webhook_version`	string	고정값 `v2`
`sms_batch.batch_id`	string	대량 문자 발신 ID
`sms_batch.name`	string \| null	대량 문자 발신 이름
`sms_batch.status`	string	종결 상태예요. 값은 `success`, `fail`, `canceled` 가운데 하나예요.
`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.canceled_count`	number	취소로 발신하지 않은 수신자 수
`sms_batch.created_at`	number	대량 문자 발신을 만든 시각(Unix 밀리초)
`sms_batch.finished_at`	number	대량 문자 발신 종결 시각(Unix 밀리초)이에요. 취소한 대량 발신은 취소 시각이에요.
`sms_batch.canceled_at`	number \| null	대량 문자 발신을 취소한 시각(Unix 밀리초)이에요. 취소하지 않았으면 `null`이에요.
`sms_batch.sheet_id`	string \| null	원본 시트 ID예요. 시트를 거치지 않은 건은 `null`이에요.
`sms_batch.occurred_at`	number	이벤트 발생 시각(Unix 밀리초)

sms_batch 본문은 대량 문자 발신 조회 API 응답에서 진행 중에만 쓰는 필드를 빼고 occurred_at을 더한 구조예요. success_count, failure_count, pending_count, blocked_count, canceled_count를 모두 더하면 total_count예요. 발신 중에 발신번호가 해지·만료되거나 발신표기번호가 삭제되면 아직 보내지 않은 항목은 실패해요. 문자별 결과는 v3 API 참조의 문자 > 발신 문자 목록 조회에 batch_id를 넘겨 확인하세요. 페이지는 cursor로 넘겨요.

서버 구현 체크리스트

수신 스키마에 최상위 webhook_version 필드를 포함하세요.
call_ended에서 비용이나 분석 필드를 기대하지 마세요.
분석 결과 저장, 후속 자동화, 비용 집계는 call_analyzed에서 실행하세요.
통화 결과는 call_status와 disconnection_reason을 함께 확인하세요.
통화 시간은 end_at - start_at으로 계산하세요.
call_context에서 에이전트가 맥락에 대해 말했는지는 consumed가 아니라 reply로 판단하세요.
event별로 본문 키를 분기하세요. operator_call_started와 operator_call_ended는 operator_call, 상담사 구간의 mid_call은 call, sms_received와 sms_sent는 sms, campaign, sms_batch는 각 리소스 키를 써요.

시작하기

코파일럿

구축

평가

배포

발신

모니터링

설정

정책

통화 이벤트

`call_started`

`mid_call`

`call_context`

`call_ended`

스크립트 형식

`call_analyzed`

상담사 통화 이벤트

`operator_call_started`

`mid_call`

`operator_call_ended`

상담사 통화 상세 조회

전달 보장과 재시도

sms_received

첨부 파일 다운로드

sms_sent

대량 발신 이벤트

`campaign`

`sms_batch`

서버 구현 체크리스트

관련 문서

​통화 이벤트

​call_started

​mid_call

​call_context

​call_ended

​스크립트 형식

​call_analyzed

​상담사 통화 이벤트

​operator_call_started

​mid_call

​operator_call_ended

​상담사 통화 상세 조회

​전달 보장과 재시도

​sms_received

​첨부 파일 다운로드

​sms_sent

​대량 발신 이벤트

​campaign

​sms_batch

​서버 구현 체크리스트

​관련 문서

통화 이벤트

`call_started`

`mid_call`

`call_context`

`call_ended`

스크립트 형식

`call_analyzed`

상담사 통화 이벤트

`operator_call_started`

`mid_call`

`operator_call_ended`

상담사 통화 상세 조회

전달 보장과 재시도

sms_received

첨부 파일 다운로드

sms_sent

대량 발신 이벤트

`campaign`

`sms_batch`

서버 구현 체크리스트

관련 문서