功能概述
实时字幕回传用于接入 TWeTalk 产品的硬件，负责将智能体对话中的用户语音识别文本和智能体回复文本实时推送到客户服务端。支持客户完成：
会话字幕展示。
对话记录存档。
业务质检与分析。
配置项说明
在智能体配置中使用以下字段完成回调：
配置项 | 是否必填 | 说明 |
SubtitleCallbackUrl | 是 | 接收字幕的回调地址，建议 HTTPS。 |
SubtitleCallbackSignKey | 否 | 回调签名密钥。配置后 TWeTalk 平台会携带签名头进行调用，可验签。（建议配置） |
SubtitleCallbackTimeout | 否 | 单次回调超时（秒），默认5。 |
回调请求协议
请求方式
Method：POST
Content-Type：application/json; charset=utf-8
请求目标：SubtitleCallbackUrl
请求头：
Header | 说明 |
Content-Type | 固定 application/json; charset=utf-8 |
X-Timestamp | 毫秒时间戳（字符串）。 |
X-Request-Id | 请求唯一 ID（UUID）。 |
Sign | 配置了 SubtitleCallbackSignKey 时携带；未配置时不携带。 |
请求体字段：
字段 | 类型 | 说明 |
session_id | string | 会话唯一标识。 |
room_id | string | 房间或连接标识。 |
product_id | string | 产品标识。 |
device_name | string | 设备标识。 |
role | string | user（用户）或 bot（智能体）。 |
text | string | 字幕文本内容。 |
timestamp_ms | number | 事件时间戳（毫秒）。 |
user_id | string | 可选字段，通常仅用户字幕时出现。 |
成功响应要求
客户服务端成功接收后，只需返回 HTTP 状态码：200。
说明：
平台当前以 HTTP 状态码判定成功，不要求响应体内容。
返回非 200 会被判定失败并触发重试策略。
建议接口保持幂等，能安全处理重复请求。
签名校验（重要）
当配置 SubtitleCallbackSignKey 后，您应在服务端进行验签：
签名串：string_to_sign = raw_json_body + X-Timestamp + X-Request-Id
签名算法：HMAC-SHA256
编码：Base64
请求头：Sign
即：Sign = Base64(HMAC_SHA256(string_to_sign, sign_key))
建议的服务端校验顺序：
1. 时效性校验：|now - X-Timestamp| < 5分钟。
2. 签名校验：按相同算法计算并比对 Sign。
3. 幂等性校验：基于 X-Request-Id 去重（Redis/DB）。
推荐接入流程
1. 部署回调接口（建议 HTTPS）。
2. 配置 SubtitleCallbackUrl。
3. 生产环境配置 SubtitleCallbackSignKey 并完成验签。
4. 按服务能力调整 SubtitleCallbackTimeout。
5. 发起真实对话，确认用户字幕和智能体字幕均可收到。
6. 演练失败场景（如超时、返回非 200）并验证幂等与重试表现。
常见问题
为什么收不到字幕？
优先检查：
1. SubtitleCallbackUrl 是否正确且可访问。
2. 接口是否返回 HTTP 200。
3. 是否被网关、防火墙或鉴权策略拦截。
为什么会收到重复字幕？
常见原因：
网络波动触发重试。
接口未做幂等处理。
建议：基于 X-Request-Id 做去重。
是否必须启用签名？
生产环境强烈建议启用，防止伪造请求与重放攻击。
