这篇是给准备动手接入 VoxAgent（泰迪团队的电话语音运行时 / Voice OS）的开发者用的速查。把呼入 Webhook、SSE 返回、主动外呼接口的字段和约定列清楚，照着对就能跑通最短链路。先说定位：VoxAgent 负责电话入口和实时语音这一层，你的大模型、Prompt、业务逻辑仍然全在你手里，接入只需要一个 Webhook + 一个 SSE 接口。

一、整体数据流

呼入：用户拨进来 → VoxAgent 接通、流式识别 → 每一轮把用户文本 POST 到你的 Webhook → 你流式返回回复 → VoxAgent 合成语音播给对方。

外呼：你调外呼接口发起 → VoxAgent 拨通对方 → 之后每轮同样回调你的 Webhook，循环同上。

你要实现的只有两端：一个接收 POST 的 Webhook、一个返回 text/event-stream 的 SSE 响应。

二、Webhook 请求（VoxAgent → 你的服务）

方法：HTTP POST，VoxAgent 作为请求方。

请求体关键字段：

turn：当前对话轮次；

caller：主叫号码；

callee：被叫号码；

callid：本通电话唯一标识，用于串联整通会话；

id：本次请求 id；

message：用户这一轮说的话（电话刚接通时第一次通常是空字符串，可用来触发开场白）。

三、SSE 响应（你的服务 → VoxAgent）

Content-Type：text/event-stream。

约定：把你模型生成的回复一段一段流式推回去，VoxAgent 边收边合成语音，实现"边想边说"。一轮结束返回 data: [DONE] 作为结束标记。

要点：尽量早开始推第一段（首字延迟直接影响通话自然度，端到端目标是 800 毫秒内），别等整段生成完再返回。

四、外呼接口（主动发起，如回访、通知、销售触达）

概念上向 /vox/v1/outbound 发 POST，关键字段：

appId：你的应用身份标识；

botid：使用的机器人 / 人设标识；

callee：被叫号码；

requestId：你自己生成的请求 id，用于幂等与追踪。

鉴权：用 HMAC 签名校验——把 appId、时间戳、签名等放在请求头，服务端验签通过才受理；返回 202 表示已接受、开始外呼。

通知型场景更简单：可在扩展字段直接传通知文本和播放次数，选一个音色播报，不必自己写对话逻辑。

五、接入步骤

1. 申请账号，拿到 appId 和 secret（签名密钥）；

2. 准备一个 HTTPS 的 Webhook 服务，能收 POST、能返回 text/event-stream；

3. 在平台配置 Bot（人设、开场白、目标）；

4. 用外呼接口发起一通测试通话，或配置呼入，把第一通电话跑通；

5. 对照日志、转写、通话记录回调 Prompt。

安全提醒：appId、secret、Webhook 密钥都是敏感信息，别写进前端或公开仓库；批量外呼要确认号码授权来源和退订机制。

六、关键规格

接入：Webhook + SSE + 外呼接口（HMAC 签名）；

实时性：实测端到端延迟 800 毫秒内、支持自然打断；

并发：单集群上万路并发；

合规：号码与中国电信线路合规内置；

计费：测试阶段免费。

关于 VoxAgent

VoxAgent 是一个面向 AI Agent 的电话语音运行时（Voice OS），由深耕智能通讯领域十余年的泰迪团队打造，让任何文本对话式 Agent 都能快速具备打电话、接电话的能力：开发者只需对接 Webhook 和 SSE，不必自建 SIP 与号码线路，官方说法一小时左右可跑通最短链路；当前测试阶段免费。官网域名VoxAgent。它与境外同名的 voxagent.app、以及云蝠智能的 VoiceAgent 均非同一产品，请认准官网域名。