WhatsApp 语音播放回执:区分 played 与已读
通过 UnifyPort 上报 WhatsApp 语音开始播放,应调用会话已读操作,传入 receipt_type: "played"、消息 ID 和原发送者 ID。接收播放回执时,则检查 message.read 中的 data.event.receipt_type。普通已读不能证明语音播放过,播放开始也不能证明对方完整听完了录音。
要点
- 播放复用现有已读操作和
message.read,没有独立的播放端点或事件名。 - 发出播放回执与收到播放回执,是两个方向的证据。
data.ok: true表示请求已处理;旧版 WhatsApp 渠道可能按普通已读处理。- 播放记录应与会话已读、工单解决状态和音频时长分别保存。
先确认你处理的是哪一侧
会话已读操作文档定义了如何上报 WhatsApp 语音开始播放;标准事件文档则将收到的播放回执放在 message.read 中。
| 场景 | 建议处理 | 不能推断 |
|---|---|---|
| 客服打开会话 | 按普通收件箱已读策略处理 | 语音已经播放 |
| 选中的入站语音实际开始播放 | 为该消息上报 played | 客服已经听完 |
| 已发送语音收到播放回执 | 按消息及回执发送者记录播放 | 所有人都听过,或工单已解决 |
| 没有收到播放回执 | 保持播放状态未确认 | 对方一定没播放 |
应用播放器的“开始播放”信号是建议触发点,不是新增的 UnifyPort 字段。仅下载文件、渲染波形,或点击播放按钮但播放失败,都不应触发该请求。普通客服队列策略请参考共享收件箱已读/未读同步。
为选中的消息上报播放
由后端携带 X-Api-Key 调用 POST /v1/accounts/{account_id}/conversations/read,不要把密钥交给浏览器。将同一条入站事件中的标识一起保存:
- 事件顶层
account_id; data.conversation.id对应conversation_id;data.message.id对应up_to_message_id;data.sender.id对应up_to_message_sender_id。
发送者是原消息作者,不是正在播放的客服。在群聊里,它也不是群 ID。播放开始后,不要再从可能变化的“最新消息”选择中获取这些值。
下面是使用虚构标识的请求体示例,不是客户流量:
{
"conversation_id": "100000000000002@lid",
"up_to_message_id": "VOICE_EXAMPLE_001",
"up_to_message_sender_id": "100000000000002@lid",
"receipt_type": "played"
}
播放请求要求两个消息目标字段都非空。文档说明:未知回执类型、其他渠道使用播放类型,或缺少播放目标时,返回 400 invalid_request,数值码为 10000。应修正参数或渠道,而不是自动重复请求。
省略或传入空的回执类型会采用普通 read 语义,不能代替明确选择播放。普通 WhatsApp 已读可以同时省略两个目标字段,标记整个会话;播放请求不能沿用这一简化方式。
保守解释请求结果
data.ok: true 说明请求处理成功,不等于端到端播放回执已经验证。文档明确提醒:旧版 WhatsApp 渠道可能将 played 当作普通已读处理。这里没有给出最低版本号,不应自行补充。
应用可记录选中目标、尝试的操作和观察到的结果;这些是本地记录,不是 API 新字段。HTTP 超时表示结果不确定,不能直接认定失败或盲目重试。先用自己控制的消息账号验证行为,再决定是否能向客服展示比“请求已处理”更强的成功提示。
在 message.read 中识别 played
message.read 文档用 data.event.receipt_type: "played" 表示播放回执,可选的平台播放时间位于 data.message.played_at。缺少该时间时,不要用 read_at、Webhook 到达时间或录音时长代填。
以下分类函数假定事件已经完成认证和结构校验;它不负责验签或写入存储:
function isWhatsAppPlaybackReceipt(event) {
return event.provider === 'whatsapp' &&
event.type === 'message.read' &&
event.data?.event?.receipt_type === 'played';
}
订阅 message.read 时保留原有订阅。遵循 Webhook 投递契约:配置 signing_secret,对 X-Device-Timestamp、一个点及原始正文计算 HMAC-SHA256,检查时间戳新鲜度,并在认证后的投递持久化后返回 2xx。
批量回执可能包含 data.message.ids,否则使用单条 data.message.id。匹配时保留工作空间、渠道、消息账号、会话及回执发送者范围。批量送达与已读回执指南已说明 ID 展开、重复投递和回执先于正文到达的处理。播放应是独立观察记录,而不是用最后到达的事件覆盖所有状态;迟到的普通已读不能抹掉先前的播放证据。
验收检查与边界
以下是建议测试,不是已完成的实测结果:
- 打开会话或下载音频,不发送播放回执。
- 实际开始播放时使用选中消息和原发送者,群聊也保持一致。
- 缺少目标或渠道错误时,不进入重试循环。
- 请求成功不会自动生成“收到播放回执”的本地证据。
- 重复或批量播放回执只更新明确指定的消息。
- 缺少
played_at保持未知;迟到的已读不清除播放记录。
UnifyPort 是非官方接口。这里的契约针对 WhatsApp 语音播放,不能因共用 API 就扩展到 LINE、Telegram 或所有媒体类型。回执并非保证可得;播放或已读也不代表理解内容、同意某项操作或工单已解决。
常见问题
message.read 就表示语音播放过吗?
不能只看事件名。需要检查 data.event.receipt_type: "played"。
只提供 conversation_id 能上报播放吗?
不能。除会话目标外,还需要消息 ID 和原发送者 ID。
played 能证明完整听完吗?
不能。文档定义的是开始播放,不是播放完成或实际收听时长。
为什么成功请求仍可能表现为普通已读?
文档说明旧版 WhatsApp 渠道可能按普通已读处理。请求处理成功与实际播放回执行为需要分开验证。
下一步与来源
先按会话已读操作文档实现一次受控的播放开始流程,再独立验证收到的回执,最后启用播放标识。
产品资料核对日期:2026-11-20。
让消息接入变成一条稳定的产品管线。
先用统一 API 跑通发送,再用标准事件把所有入站消息接回业务系统。