WhatsApp Voice Message Playback Receipts: played vs Read
To report that a WhatsApp voice message started playing through UnifyPort, call the conversation read operation with receipt_type: "played", the message ID, and its original sender ID. To recognize an incoming playback receipt, inspect data.event.receipt_type inside message.read. An ordinary read receipt is not playback evidence, and a playback-start observation is not proof that someone listened to the entire recording.
Key takeaways
- Playback uses the existing read operation and
message.readevent, not a separate playback endpoint or event name. - Sending a playback receipt and receiving one are opposite directions of evidence.
data.ok: trueconfirms request processing; older WhatsApp channel versions may process the request as an ordinary read.- Store playback evidence independently from read state, ticket resolution, and audio duration.
First decide which side of the voice message you are on
The read operation reference documents reporting that a WhatsApp voice message started playing. The standard event reference documents incoming playback receipts under message.read.
| Situation | Appropriate behavior | Do not infer |
|---|---|---|
| An agent opens a conversation | Apply your ordinary inbox read policy | A voice message played |
| Playback of a selected inbound voice message actually starts | Consider sending receipt_type: "played" for that message | The agent finished listening |
| A playback receipt arrives for a sent voice message | Record playback for the identified messages and sender | Every participant listened, or the ticket is resolved |
| No playback receipt arrives | Leave playback unconfirmed | Playback definitely did not happen |
Your application’s playback-start signal is a recommended trigger, not a new UnifyPort field. Do not send the receipt merely because a file was downloaded, a waveform rendered, or a play button clicked while the player failed to start. Ordinary queue behavior belongs in the shared-inbox read/unread workflow.
Report playback for the selected message
Use POST /v1/accounts/{account_id}/conversations/read from your backend with X-Api-Key. Keep the key out of the browser. Preserve the selected inbound event’s identifiers together:
account_idfrom the event envelope;conversation_idfromdata.conversation.id;up_to_message_idfromdata.message.id;up_to_message_sender_idfromdata.sender.id.
The sender is the original message author, not the agent playing it. In a group, it is not the group ID. Do not read these values from a mutable “latest message” selection after playback starts.
Illustrative request body with fictional identifiers, not captured traffic:
{
"conversation_id": "100000000000002@lid",
"up_to_message_id": "VOICE_EXAMPLE_001",
"up_to_message_sender_id": "100000000000002@lid",
"receipt_type": "played"
}
For playback, both message-target fields must be non-empty. The reference specifies 400 invalid_request with numeric code 10000 for an unknown receipt type, playback on another channel, or a missing playback target. Correct the input or channel rather than automatically repeating the request.
An omitted or empty receipt type uses ordinary read semantics. That default is not a substitute for explicitly selecting playback. Likewise, ordinary WhatsApp reads may omit both target fields to mark the conversation read; do not carry that shortcut into a playback request.
Interpret the request result conservatively
The operation returns data.ok: true when processing succeeds. It does not certify end-to-end playback-receipt behavior: the reference explicitly warns that older WhatsApp channel versions may treat played as an ordinary read. No minimum version number is documented here, so do not invent one.
Keep a local record of the selected target, attempted action, and observed result. These are application records, not additional API fields. An HTTP timeout leaves the result uncertain; it is not a reason to claim failure or blindly repeat the action. Validate behavior with accounts you control before showing operators a stronger success label than “request processed.”
Recognize played inside message.read
The message.read reference uses data.event.receipt_type: "played" for playback. Its optional provider-reported time is data.message.played_at. Do not substitute read_at, webhook arrival time, or the recording’s duration when that timestamp is absent.
This small classifier assumes an already authenticated and validated event. It neither verifies signatures nor updates storage:
function isWhatsAppPlaybackReceipt(event) {
return event.provider === 'whatsapp' &&
event.type === 'message.read' &&
event.data?.event?.receipt_type === 'played';
}
Subscribe to message.read, preserving existing subscriptions. Follow the webhook delivery contract: configure signing_secret, verify HMAC-SHA256 over X-Device-Timestamp, a dot, and the raw body, check timestamp freshness, and persist authenticated deliveries before acknowledging with 2xx.
A receipt can cover data.message.ids; otherwise use the singular data.message.id. Preserve workspace, provider, account, conversation, and acknowledging sender scope. The batch receipt guide covers ID expansion, duplicates, and receipts arriving before message content. Add playback as a separate observation rather than replacing all receipt state with the last event received. A later ordinary read must not erase an earlier playback observation.
Acceptance checks and limits
Proposed tests, not reported results:
- Opening a conversation or downloading audio does not send a playback receipt.
- Actual playback start uses the selected message and original sender, including in groups.
- A missing target or wrong provider is rejected without a retry loop.
- Request success does not automatically create an incoming playback observation.
- A duplicate or batched playback receipt updates only its explicit message scope.
- Missing
played_atstays unknown; a later read does not erase playback evidence.
UnifyPort is an unofficial interface. This contract concerns WhatsApp voice playback; do not extend it to LINE, Telegram, or every media type because they share an API surface. Receipt availability is not guaranteed, and neither playback nor reading establishes comprehension, consent, or support resolution.
FAQ
Does message.read mean a voice message was played?
Not by its event name alone. Check for data.event.receipt_type: "played".
Can I report playback with just conversation_id?
No. Playback requires both the message ID and original sender ID, in addition to the conversation target.
Does played prove the whole recording was heard?
No. The documented action reports playback start, not completion or listening duration.
Why can a successful request behave like a normal read?
The reference warns that older WhatsApp channel versions may process playback as an ordinary read. Request processing and observed playback behavior are separate checks.
Next step and sources
Implement one controlled playback-start flow against the read operation reference, then verify the incoming receipt separately before enabling playback badges.
Product references checked on 2026-11-20:
Turn messaging integration into a stable product pipeline.
Start by sending through one API, then bring every inbound message back into your business system with standard events.