跳转到内容

Webhook

声邻 Voicelen 会在关键业务事件发生时,主动 POST JSON 到你配置的 URL。适合用于 CRM 同步、工单触发、实时告警等场景。

登录控制台 → 管理 → Webhook 填写接收 URL、订阅事件、超时等。首次创建会生成一次性 Secret,用于签名验证,请立即保存。

  • POST 你配置的 URL
  • Content-Type: application/json
  • 请求体为事件对象,所有事件统一信封
  • 2xx 视为投递成功,其它状态码或超时视为失败,触发重试
请求头
X-Voicelen-Event-Id
事件唯一 ID,用于幂等去重
X-Voicelen-Event-Type
事件类型,如 call.ended
X-Voicelen-Timestamp
请求发出的 Unix 秒级时间戳
X-Voicelen-Signature
sha256={body 的 HMAC-SHA256 hex}

服务端用你的 Secret 对完整 body(bytes)做 HMAC-SHA256,十六进制写入 X-Voicelen-Signature。客户端应用相同方法验证,防止伪造。

  • 首次投递失败后延迟 1 分钟重试一次
  • 仍失败再延迟 10 分钟重试一次
  • 2 次重试都失败后标记为 failed,不再投递
  • Event ID 幂等:同一事件 ID 永远只投递一次

事件按业务场景拆分:通话事件按来源分为外呼任务/呼入/定时外呼/座席主动外呼四组,每组各含 started/answered/ended 三阶段。订阅方按场景选事件,无需二次过滤 source_type。

所有 xxx.call.started / xxx.call.answered / xxx.call.ended 共用同一份 payload,不同阶段字段值不同(未发生的时间字段为空字符串)。

字段 .started .answered .ended
call_id / direction / source_type / customer_phone / agent_* / user_* / extra ✅ ✅ ✅
start_time ✅ ✅ ✅
answer_time “” ✅ ✅(若接听)
end_time / duration / billsec / hangup_cause / hangup_by “” / 0 “” / 0 ✅
recording_url “” “” ✅(若有录音)

extra 字段(object)是通话上下文统一字段,分两层:**顶层**是通话变量 —— 定时/立即外呼时入参 extra 直接写入,外呼任务通话由 OutboundTaskItem.Extra 优先 + Customer.Extra 兜底合并,呼入通话取自匹配的 Customer.Extra,常用于业务系统对账(用 biz_id 等回查);**collect_info 子对象**是 AI Agent 在通话中收集到的字段 —— 通话发起(CallRecord 创建)时就按 Agent 配置把全部字段以空串写入,收集到再实时更新值,因此 started 事件以及未接通的通话都带完整字段列表,字段恒定存在,空串代表未收集或客户拒答。

  • outbound_task.call.started — 外呼任务发起通话(CallRecord 落库后立即发)
  • outbound_task.call.answered — 外呼任务客户接听
  • outbound_task.call.ended — 外呼任务通话结束
  • inbound.call.started — 呼入通话开始(与 answered 几乎同时触发,呼入在 CHANNEL_ANSWER 才建 CallRecord)
  • inbound.call.answered — 呼入通话已接听
  • inbound.call.ended — 呼入通话结束
  • outbound_agent.call.started — 定时外呼发起通话(source_type=direct)
  • outbound_agent.call.answered — 客户接听
  • outbound_agent.call.ended — 通话结束
  • manual.call.started — 座席在工作台拨打客户号码
  • manual.call.answered — 客户接听
  • manual.call.ended — 通话结束

outbound_task.completed — 外呼任务完成

Section titled “outbound_task.completed — 外呼任务完成”

call.analyzed — AI 分析完成(跨来源共用)

Section titled “call.analyzed — AI 分析完成(跨来源共用)”

call.analyzed 事件对所有来源的通话共用,订阅方可按 source_type 判断;extra 与通话事件同源(同一条 CallRecord.Extra,其中 collect_info 是通话结束时的最终值),便于按 biz_id 对账。

鄂ICP备2022005956号-2