웹훅 스키마

이벤트별 페이로드 필드와 예시를 정리했습니다. 본문 키는 이벤트마다 call, operator_call, sms, campaign, sms_batch로 다릅니다. 본문 식별자는 call_id, operator_call_id, campaign_id, batch_id처럼 리소스별 키를 쓰며 REST API 응답의 id와 이름이 다릅니다.

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

통화 이벤트

통화 데이터 웹훅은 통화 진행 상태와 분석 완료 상태를 나누어 전송합니다. call_analyzed는 통화 종료 후 비동기로 전송됩니다.

`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_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	통화 데이터 저장 제외 여부

통화 시간은 end_at - start_at으로 계산합니다.

녹음 파일 다운로드

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": [
        { "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.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 통화에서 상담원에게 전환된 뒤의 이벤트입니다. 안내 후 전환과 Desk 이어받기에 적용됩니다. 통화 데이터 웹훅 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>'

일부 과거 통화는 만료가 없는 다운로드 URL로 반환될 수 있습니다. 상담원 통화 조회는 통화 조회와 같은 워크스페이스 요청 한도를 공유합니다. 주기적으로 폴링하지 말고 웹훅을 받은 뒤 필요한 통화만 조회하세요.

단건 응답의 recording_url은 15분 뒤 만료되는 서명 URL입니다. URL을 저장해 두지 말고 재생 시점에 다시 조회하세요.

전달 보장과 재시도

수신 서버가 응답을 돌려주면 상태 코드와 무관하게 그 시도는 끝납니다. 4xx나 5xx로 재시도를 유도할 수 없습니다. 응답이 없거나 연결이 끊기면 제한된 횟수만 재시도합니다. 수신 서버가 응답한 뒤 vox.ai가 결과를 저장하기 전에 장애가 나면 같은 이벤트가 다시 전송됩니다. 같은 이벤트를 한 번만 처리하려면 다음 키를 쓰세요. 통화 이벤트는 (event, call_id), 상담원 통화 이벤트는 (event, operator_call_id)입니다. mid_call은 AI 구간에서 call_id, 상담원 구간에서 operator_call_id를 쓰세요. 여기에 event, occurred_at, event_type, event_data를 더해 키를 구성하세요.

응답이 늦어 타임아웃되면 재시도로 같은 이벤트가 다시 전송됩니다. 요청을 먼저 저장하고 2xx를 바로 반환한 뒤 후속 처리는 비동기로 실행하세요.

sms_received

sms_received는 워크스페이스 번호로 SMS나 MMS를 수신할 때 전송됩니다. 워크스페이스 웹훅 전용이며 설정 > 웹훅의 이벤트 구독에서 수신 문자를 선택한 워크스페이스에만 전송됩니다. 본문 키는 통화 이벤트와 달리 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은 image/jpeg, image/png, image/gif 중 저장된 MIME 타입을 그대로 따릅니다. 같은 워크스페이스가 소유한 file_key만 받을 수 있습니다. 전체 파라미터는 v3 API 참조의 파일 > 파일 다운로드에서 확인하세요.

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

서명 방식은 통화 데이터 웹훅과 동일합니다. 대시보드 설정 > 웹훅의 이벤트 구독에서 수신 문자를 선택하고 저장하면 전송됩니다. 기본값은 선택 해제이고 선택한 이후 수신분부터 전송됩니다.

대량 발신 이벤트

campaign과 sms_batch는 대시보드 설정 > 웹훅의 이벤트 구독에서 캠페인 종결과 문자 대량 발신 종결을 선택하고 저장합니다. 워크스페이스 설정 API의 webhook_event_subscriptions에 이벤트 값을 추가해도 됩니다.

이 두 이벤트도 워크스페이스 웹훅 URL과 같은 서명 방식을 따릅니다. 중복 처리는 전달 보장과 재시도를 따르세요.

`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로 종결될 때 전송됩니다. 발송이 시작되어 상태가 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을 추가한 구조입니다.

서버 구현 체크리스트

수신 스키마에 최상위 webhook_version 필드를 포함하세요.
call_ended에서 비용이나 분석 필드를 기대하지 마세요.
분석 결과 저장, 후속 자동화, 비용 집계는 call_analyzed에서 실행하세요.
통화 결과는 call_status와 disconnection_reason을 함께 확인하세요.
통화 시간은 end_at - start_at으로 계산하세요.
operator_call_started와 operator_call_ended는 operator_call 키를 사용합니다.
상담원 구간의 mid_call은 call 키를 사용합니다.
sms_received, campaign, sms_batch는 각 리소스 키를 사용합니다.
event별로 본문 키를 분기하세요.

시작하기

빌드하기

배포하기

발신

모니터링

기타

통화 이벤트

`call_started`

`mid_call`

`call_ended`

녹음 파일 다운로드

스크립트 형식

`call_analyzed`

상담원 통화 이벤트

`operator_call_started`

`mid_call`

`operator_call_ended`

상담원 통화 상세 조회

전달 보장과 재시도

sms_received

첨부 파일 다운로드

대량 발신 이벤트

`campaign`

`sms_batch`

서버 구현 체크리스트

관련 문서

​통화 이벤트

​call_started

​mid_call

​call_ended

​녹음 파일 다운로드

​스크립트 형식

​call_analyzed

​상담원 통화 이벤트

​operator_call_started

​mid_call

​operator_call_ended

​상담원 통화 상세 조회

​전달 보장과 재시도

​sms_received

​첨부 파일 다운로드

​대량 발신 이벤트

​campaign

​sms_batch

​서버 구현 체크리스트

​관련 문서

통화 이벤트

`call_started`

`mid_call`

`call_ended`

녹음 파일 다운로드

스크립트 형식

`call_analyzed`

상담원 통화 이벤트

`operator_call_started`

`mid_call`

`operator_call_ended`

상담원 통화 상세 조회

전달 보장과 재시도

sms_received

첨부 파일 다운로드

대량 발신 이벤트

`campaign`

`sms_batch`

서버 구현 체크리스트

관련 문서