Webhook
声邻 Voicelen 会在关键业务事件发生时,主动 POST JSON 到你配置的 URL。适合用于 CRM 同步、工单触发、实时告警等场景。
登录控制台 → 管理 → Webhook 填写接收 URL、订阅事件、超时等。首次创建会生成一次性 Secret,用于签名验证,请立即保存。
POST你配置的 URLContent-Type: application/json- 请求体为事件对象,所有事件统一信封
- 2xx 视为投递成功,其它状态码或超时视为失败,触发重试
X-Voicelen-Event-IdX-Voicelen-Event-TypeX-Voicelen-TimestampX-Voicelen-Signature服务端用你的 Secret 对完整 body(bytes)做 HMAC-SHA256,十六进制写入 X-Voicelen-Signature。客户端应用相同方法验证,防止伪造。
- 首次投递失败后延迟 1 分钟重试一次
- 仍失败再延迟 10 分钟重试一次
- 2 次重试都失败后标记为 failed,不再投递
- Event ID 幂等:同一事件 ID 永远只投递一次
事件按业务场景拆分:通话事件按来源分为外呼任务/呼入/定时外呼/座席主动外呼四组,每组各含 started/answered/ended 三阶段。订阅方按场景选事件,无需二次过滤 source_type。
通话事件通用 Payload
Section titled “通话事件通用 Payload”所有 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 事件以及未接通的通话都带完整字段列表,字段恒定存在,空串代表未收集或客户拒答。
外呼任务通话
Section titled “外呼任务通话”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— 呼入通话结束
定时外呼通话(含立即拨)
Section titled “定时外呼通话(含立即拨)”outbound_agent.call.started— 定时外呼发起通话(source_type=direct)outbound_agent.call.answered— 客户接听outbound_agent.call.ended— 通话结束
座席主动外呼
Section titled “座席主动外呼”manual.call.started— 座席在工作台拨打客户号码manual.call.answered— 客户接听manual.call.ended— 通话结束
outbound_task.completed — 外呼任务完成
Section titled “outbound_task.completed — 外呼任务完成”chat.started — 在线客服会话开始
Section titled “chat.started — 在线客服会话开始”chat.ended — 在线客服会话结束
Section titled “chat.ended — 在线客服会话结束”call.analyzed — AI 分析完成(跨来源共用)
Section titled “call.analyzed — AI 分析完成(跨来源共用)”call.analyzed 事件对所有来源的通话共用,订阅方可按 source_type 判断;extra 与通话事件同源(同一条 CallRecord.Extra,其中 collect_info 是通话结束时的最终值),便于按 biz_id 对账。