← Все статьи
Руководство

Квитанции воспроизведения голосовых WhatsApp: played и read

Чтобы через UnifyPort сообщить, что голосовое сообщение WhatsApp начало воспроизводиться, вызовите операцию отметки прочтения с receipt_type: "played", ID сообщения и ID его исходного отправителя. Во входящей квитанции проверяйте data.event.receipt_type внутри message.read. Обычное прочтение не подтверждает воспроизведение, а начало воспроизведения не доказывает, что запись прослушали целиком.

Главное

  • Используются существующая операция прочтения и событие message.read, а не отдельный метод или новое имя события.
  • Отправка квитанции воспроизведения и получение такой квитанции — разные направления подтверждения.
  • data.ok: true означает обработку запроса. Старые версии канала WhatsApp могут обработать его как обычное прочтение.
  • Храните сведения о воспроизведении отдельно от прочтения чата, закрытия обращения и длительности аудио.

Сначала определите сторону взаимодействия

Справочник операции прочтения описывает, как сообщить о начале воспроизведения голосового WhatsApp. Справочник стандартных событий помещает входящие квитанции воспроизведения в message.read.

СитуацияРекомендуемое действиеЧего нельзя заключать
Оператор открыл чатПрименить обычную политику прочтенияГолосовое воспроизвелось
Выбранное входящее голосовое действительно начало игратьПри необходимости отправить played для этого сообщенияОператор дослушал запись
Пришла квитанция для отправленного голосовогоЗаписать воспроизведение для указанных сообщений и участникаВсе участники прослушали запись или обращение решено
Квитанция не пришлаОставить воспроизведение неподтверждённымПолучатель точно ничего не воспроизводил

Сигнал начала воспроизведения от проигрывателя приложения — рекомендуемый триггер, а не новое поле UnifyPort. Не отправляйте квитанцию только из-за загрузки файла, отображения звуковой волны или нажатия кнопки, если воспроизведение не началось. Обычная работа очереди описана в руководстве по прочитанным и непрочитанным чатам общего inbox.

Сообщите о воспроизведении выбранного сообщения

Вызывайте POST /v1/accounts/{account_id}/conversations/read с серверной стороны, используя X-Api-Key. Не передавайте ключ браузеру. Сохраните вместе идентификаторы из одного входящего события:

  • 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"
}

Для воспроизведения оба поля целевого сообщения должны быть непустыми. Неизвестный тип квитанции, played на другом канале или отсутствующая цель дают 400 invalid_request с числовым кодом 10000. Исправьте входные данные или канал, а не повторяйте запрос автоматически.

Пропущенный или пустой тип квитанции использует обычную семантику read. Это не замена явному указанию воспроизведения. Для обычного прочтения WhatsApp оба целевых поля можно опустить, чтобы отметить чат целиком; к запросу воспроизведения такое сокращение неприменимо.

Ограничьте смысл успешного ответа

data.ok: true подтверждает обработку запроса, но не сквозную работу квитанции воспроизведения. Документация прямо предупреждает: старые версии канала WhatsApp могут обработать played как обычное прочтение. Минимальный номер версии здесь не указан — не добавляйте его самостоятельно.

Сохраняйте выбранную цель, предпринятое действие и наблюдаемый результат в локальном журнале. Это данные приложения, а не дополнительные поля API. Тайм-аут HTTP оставляет результат неопределённым: он не доказывает неудачу и не оправдывает безусловный повтор. Проверьте поведение на подконтрольных аккаунтах обмена сообщениями, прежде чем показывать оператору статус сильнее, чем «запрос обработан».

Распознавайте played внутри message.read

В справочнике 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, проверяйте HMAC-SHA256 от X-Device-Timestamp, точки и исходного тела, контролируйте свежесть временной метки и надёжно сохраняйте проверенную доставку перед ответом 2xx.

Пакетная квитанция может содержать data.message.ids; иначе используйте одиночный data.message.id. Сохраняйте область workspace, провайдера, аккаунта, чата и участника, приславшего квитанцию. Руководство по пакетным квитанциям доставки и прочтения объясняет обработку ID, дублей и квитанций, приходящих раньше текста сообщения. Добавляйте воспроизведение как отдельное наблюдение, а не заменяйте всё состояние последним прибывшим событием. Поздняя обычная квитанция прочтения не должна стирать ранее полученное подтверждение воспроизведения.

Проверки и ограничения

Предлагаемые тесты, а не отчёт об уже выполненных испытаниях:

  1. Открытие чата и загрузка аудио не отправляют квитанцию воспроизведения.
  2. Реальный старт использует выбранное сообщение и его исходного отправителя, в том числе в группе.
  3. Отсутствующая цель или неверный канал не запускают цикл повторов.
  4. Успех запроса не создаёт искусственное входящее подтверждение воспроизведения.
  5. Дубликаты и пакетные квитанции обновляют только явно указанные сообщения.
  6. Отсутствующий played_at остаётся неизвестным; позднее прочтение не стирает воспроизведение.

UnifyPort — неофициальный интерфейс. Этот контракт относится к голосовым WhatsApp: общая поверхность API не переносит его на LINE, Telegram или все типы медиа. Получение квитанции не гарантировано. Ни воспроизведение, ни прочтение не доказывают понимание содержания, согласие или решение обращения.

FAQ

Означает ли message.read, что голосовое воспроизведено?

Не по одному имени события. Проверяйте data.event.receipt_type: "played".

Можно ли передать только conversation_id?

Нет. Для воспроизведения нужны также ID сообщения и ID его исходного отправителя.

Доказывает ли played прослушивание всей записи?

Нет. Операция сообщает о начале воспроизведения, а не о завершении или фактической длительности прослушивания.

Почему успешный запрос может работать как обычное прочтение?

Документация допускает такое поведение старых версий канала WhatsApp. Обработку запроса и наблюдаемое поведение квитанций проверяют отдельно.

Следующий шаг и источники

Реализуйте один контролируемый сценарий начала воспроизведения по справочнику операции прочтения, затем отдельно проверьте входящую квитанцию и только после этого включайте индикатор воспроизведения.

Документация продукта проверена 2026-11-20:

UnifyPort API

Превратите интеграцию сообщений в стабильный продуктовый pipeline.

Начните с отправки через единый API, затем возвращайте входящие сообщения в бизнес-систему стандартными событиями.