← 所有文章
教程

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 展开、重复投递和回执先于正文到达的处理。播放应是独立观察记录,而不是用最后到达的事件覆盖所有状态;迟到的普通已读不能抹掉先前的播放证据。

验收检查与边界

以下是建议测试,不是已完成的实测结果:

  1. 打开会话或下载音频,不发送播放回执。
  2. 实际开始播放时使用选中消息和原发送者,群聊也保持一致。
  3. 缺少目标或渠道错误时,不进入重试循环。
  4. 请求成功不会自动生成“收到播放回执”的本地证据。
  5. 重复或批量播放回执只更新明确指定的消息。
  6. 缺少 played_at 保持未知;迟到的已读不清除播放记录。

UnifyPort 是非官方接口。这里的契约针对 WhatsApp 语音播放,不能因共用 API 就扩展到 LINE、Telegram 或所有媒体类型。回执并非保证可得;播放或已读也不代表理解内容、同意某项操作或工单已解决。

常见问题

message.read 就表示语音播放过吗?

不能只看事件名。需要检查 data.event.receipt_type: "played"。

只提供 conversation_id 能上报播放吗?

不能。除会话目标外,还需要消息 ID 和原发送者 ID。

played 能证明完整听完吗?

不能。文档定义的是开始播放,不是播放完成或实际收听时长。

为什么成功请求仍可能表现为普通已读?

文档说明旧版 WhatsApp 渠道可能按普通已读处理。请求处理成功与实际播放回执行为需要分开验证。

下一步与来源

先按会话已读操作文档实现一次受控的播放开始流程,再独立验证收到的回执,最后启用播放标识。

产品资料核对日期:2026-11-20。

UnifyPort API

让消息接入变成一条稳定的产品管线。

先用统一 API 跑通发送,再用标准事件把所有入站消息接回业务系统。