An agent opens a WhatsApp conversation, sees a voice note, and presses play. If the audio fails to load, your inbox can still mark the conversation as read. A playback receipt should wait until the audio player confirms that playback started.
With UnifyPort’s WhatsApp integration, your app can report playback of an incoming voice note and record playback receipts for voice notes it sent. These are two separate flows, and each has its own source of evidence.
Report playback when the audio starts
When the player confirms playback, send POST /v1/accounts/{account_id}/conversations/read from your backend with your workspace X-Api-Key. Use the account, conversation, message, and sender from the inbound event for the voice note being played. Capture those IDs when the agent selects the note so a conversation refresh can’t change the target. UnifyPort conversation read API
Here’s an example request body with fictional IDs.
{
"conversation_id": "100000000000001@g.us",
"up_to_message_id": "VOICE_EXAMPLE_001",
"up_to_message_sender_id": "100000000000002@lid",
"receipt_type": "played"
}
Both message target fields are required for played. In a group chat, conversation_id identifies the group and up_to_message_sender_id identifies the person who sent the voice note. Read the latter from data.sender.id in the inbound event. UnifyPort conversation read API
An HTTP 200 with data.ok: true confirms that UnifyPort processed the request. Older WhatsApp channel versions may process played as an ordinary read. If you’re testing the integration with two accounts you control, check for the playback receipt on the sending side as a separate step. UnifyPort conversation read API
Detect playback receipts on the sending side
UnifyPort delivers WhatsApp playback receipts through message.read. After verifying the webhook, check data.event.receipt_type to identify a playback receipt. A single event can acknowledge several messages through data.message.ids. For a single-message receipt, use data.message.id. UnifyPort message.read reference
function getPlayedMessageIds(event) {
if (
event.provider !== "whatsapp" ||
event.type !== "message.read" ||
event.data?.event?.receipt_type !== "played"
) {
return [];
}
const { id, ids } = event.data.message;
return ids?.length ? ids : [id];
}
Update only the messages identified by the receipt, scoped to the account, conversation, and person who acknowledged them. Store data.message.played_at when the provider supplies it. If it’s missing, you can still record that playback was reported and leave the playback time unknown. UnifyPort message.read reference
Keep playback separate from inbox state
Store read and playback observations independently so a later read event preserves an earlier playback receipt. Before adding a Playback started badge, test three cases: opening the conversation, failing to load the audio after pressing play, and successfully starting playback. Only the third should trigger your playback report. Use the badge to communicate the event you observed. Listening duration and completion are separate signals.
Adapted from the UnifyPort technical guide with AI-assisted editing.
Top comments (0)