回调｜玲声开放平台文档

通话结束时把结果推到你的服务器。登记、推送格式、验签。

事件：call.ended、call.summarized。每通最多推 3 次（立刻、2 秒后、8 秒后），你回 2xx 就算送到；跳转（3xx）算失败。

登记回调

POSThttps://aicall.lingshengai.com/api/v1/webhooks

登记一个接收地址。只收 https 的公网地址。

请求体（JSON）

字段	类型	必填	说明
`url`	`string`	否	接收地址，https。
`events`	`string[] \| null`	否	订阅哪些事件。不填只订 call.ended。
`secret`	`string`	否	验签用的密钥。不填我们生成一个。

字段	类型	说明
`webhook`	`object`	登记好的这一条。
`secret`	`string`	验签用的密钥，只在这里显示一次，请存好。
`secret_note`	`string`	一句提醒：密钥只显示这一次。

登记一个回调地址

curl -X POST https://aicall.lingshengai.com/api/v1/webhooks \
  -H "Authorization: Bearer lsk_你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://你的域名/hooks/lingsheng",
        "events": ["call.ended"]
      }'

回来的 secret 用来验签：X-Lingsheng-Signature 是 sha256=<hex>，hex 是用 secret 对「X-Lingsheng-Timestamp 的值 + . + 原始 body」算的 HMAC-SHA256。摘要有时比挂机晚一点 —— 那一条会先带 pending，就绪后再推一条。

推送的内容

请求头 X-Lingsheng-Event 是事件名。请求体是 JSON：

字段	类型	说明
`event`	`string`	call.ended：刚挂断；call.summarized：摘要出来了。
`callId`	`integer \| null`	你拨号时拿到的编号。打进来的电话为 null。
`callUuid`	`string \| null`	通话的另一个编号。
`direction`	`string`	outbound 拨出 · inbound 打进。
`from`	`string`	主叫号码。
`to`	`string`	被叫号码。
`numbersMasked`	`boolean`	对方号码是否打了码（如 138****1234）。
`outcome`	`string`	结局，比如 answered。
`answeredAt`	`string \| null`	接通时间（UTC）。
`endedAt`	`string \| null`	挂断时间（UTC）。
`durationSeconds`	`integer \| null`	接通到挂断的秒数。
`billableMinutes`	`integer \| null`	计费分钟。
`unitPriceFen`	`integer \| null`	每分钟单价，单位分。
`costFen`	`integer \| null`	这一通的费用，单位分。
`summary`	`string \| null`	摘要。还没出来时为 null。
`category`	`string \| null`	通话分类。
`pending`	`boolean`	true 表示摘要还没出来，出来后会再推一条 call.summarized（要订阅它）。
`detailUrl`	`string`	这一通的详情地址，用令牌去取。

验签

取请求头 X-Lingsheng-Timestamp 的值和原始请求体（别先解析再序列化）。
用登记时拿到的 secret，对「时间戳 + . + 请求体」算 HMAC-SHA256，得到十六进制串。
和请求头 X-Lingsheng-Signature 去掉 sha256= 之后的部分比较，一致才处理。

管理回调

GEThttps://aicall.lingshengai.com/api/v1/webhooks

你登记过的全部回调地址，停用的也在里面。

字段	类型	说明
`items`	`object[]`	回调列表，每一条的格式同「查一条回调」。
`events`	`string[]`	可以订阅的事件名。

GEThttps://aicall.lingshengai.com/api/v1/webhooks/{hook_id}

一条回调的地址、订阅和开关。

参数

字段	类型	必填	说明
`hook_id`路径	`string`	是	回调编号。

字段	类型	说明
`id`	`string`	回调编号。
`url`	`string`	接收地址。
`events`	`string[]`	订阅的事件。
`active`	`boolean`	是否启用。
`createdAt`	`string`	登记时间（UTC）。
`updatedAt`	`string`	最近修改时间（UTC）。

PATCHhttps://aicall.lingshengai.com/api/v1/webhooks/{hook_id}

改地址、订阅或开关。没给的不动。

参数

字段	类型	必填	说明
`hook_id`路径	`string`	是	回调编号。

请求体（JSON）

字段	类型	必填	说明
`url`	`string \| null`	否	新的接收地址。
`events`	`string[] \| null`	否	新的订阅。
`active`	`boolean \| null`	否	true 启用，false 停用。

字段	类型	说明
`id`	`string`	回调编号。
`url`	`string`	接收地址。
`events`	`string[]`	订阅的事件。
`active`	`boolean`	是否启用。
`createdAt`	`string`	登记时间（UTC）。
`updatedAt`	`string`	最近修改时间（UTC）。

DELETEhttps://aicall.lingshengai.com/api/v1/webhooks/{hook_id}

删掉一条回调。成功回 204，没有内容。

参数

字段	类型	必填	说明
`hook_id`路径	`string`	是	回调编号。

回调

登记回调

推送的内容

验签

管理回调

本页目录