> ## Documentation Index > Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt > Use this file to discover all available pages before exploring further. # WhatsApp echo message updated > Обработка событий статуса эхо-сообщений: доставлено, прочитано, отправлено с задержкой и сбой. ## Что это такое Подпишитесь на `whatsapp.echo_message.updated`. Вы получаете это событие, когда YCloud обрабатывает соответствующий статус исходящего эхо-сообщения для Агента, созданного через API. Сохраняйте содержимое сообщения из события создания: обновления статуса не содержат текст сообщения и `type`. Обновления с ошибкой содержат сведения об исходной ошибке, если они доступны. Текущий контракт сохраняет имя события неизменным и передает изменения статуса в поле `whatsappMessage`, что соответствует объекту, используемому соответствующим событием создания. ## Перед началом работы 1. Подключите Агента через [публичный REST API](/ru/api-reference/meta-business-agents/onboard). 2. Подпишите активную конечную точку Webhook в том же аккаунте на `whatsapp.echo_message.updated`. 3. Проверяйте `YCloud-Signature` по исходному телу запроса, надежно сохраняйте каждое событие и обрабатывайте его идемпотентно. Агенты, созданные в Консоли, не отправляют этот пользовательский Webhook. Синхронизация их Входящих выполняется отдельным потоком. Инструкции по настройке конечной точки см. в разделе [Настройка вебхуков](/ru/api-reference/guides/api-fundamentals/configure-webhooks#subscribe-to-echo-and-handover-events). ## Принцип работы Во всех примерах используются фиктивные идентификаторы. Маршрутизируйте по внешнему свойству `type` и считывайте `whatsappMessage`, а не `whatsappMetaBusinessAgent`, `whatsappEchoMessage` или `data`. Выполняйте дедупликацию повторных доставок по внешнему `id`. Внешнее поле `createTime` содержит время события Webhook; вложенное поле `updateTime` и временные метки статусов представляют собой исходное время в формате RFC 3339. * Сопоставляйте обновления с событием создания по `id` или `wamid` в рамках вашего аккаунта и бизнес-номера. * Телефон клиента и BSUID независимы. Если исходный статус содержит одновременно `recipient_id` и `recipient_user_id`, событие включает `to` вместе с `recipientUserId` или `parentRecipientUserId`. * Если элемент статуса не содержит этих идентификаторов, а тот же обратный вызов включает ровно один контакт, YCloud может использовать явные `wa_id` и `user_id` этого контакта. При отсутствии контактов или наличии нескольких отсутствующие идентификаторы опускаются; они никогда не выводятся друг из друга. * `from` включается только тогда, когда исходный обратный вызов предоставляет корректный отображаемый номер телефона компании. Он не формируется из `phoneNumberId`. * Храните историю событий отдельно от текущего статуса сообщения. Запоздалое событие `sent` может поступить после `read`; зафиксируйте его, не понижая текущий статус. * Приведенный ниже пример с запоздалой отправкой относится к сообщению из примера с прочтением. Пример со сбоем относится к другому сообщению. * Повторяющиеся неизмененные статусы одинакового ранга подавляются во время обработки. Это не гарантирует доставку HTTP ровно один раз (exactly-once). * Статус, полученный до записи соответствующего эхо-сообщения, может быть повторно запрошен внутренне. Не полагайтесь на порядок доставки. * Обычные статусы сообщений, отправленных через API, используют [`whatsapp.message.updated`](/ru/api-reference/guides/examples/webhook-examples/whatsapp-message-updated-webhook-examples), а не это событие. ## Запрос YCloud отправляет эти тела JSON в HTTP-запросах `POST` на настроенный вами URL Webhook. ## Ответ Возвращайте ответ `2xx` после успешного сохранения каждого события. Длительные операции выполняйте асинхронно. ## Эхо-сообщение доставлено ### Запрос Сопоставляйте с событием создания по id или wamid. События обновления не содержат текст и тип сообщения. ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "id": "evt_example_echo_delivered", "type": "whatsapp.echo_message.updated", "apiVersion": "v2", "createTime": "2026-09-09T02:00:03.000Z", "whatsappMessage": { "id": "MESSAGE_ID", "wamid": "wamid.EXAMPLE", "wabaId": "WABA_ID", "from": "+12025550123", "to": "+12025550124", "recipientUserId": "GB.898232076600896", "status": "delivered", "updateTime": "2026-09-09T02:00:01.000Z", "deliverTime": "2026-09-09T02:00:01.000Z" } } ``` ### Ответ ```http theme={"theme":{"light":"github-light","dark":"github-dark"}} HTTP/1.1 200 OK ``` ### Пояснение Зафиксируйте переход в статус доставки и сохраните текст сообщения, полученный в событии создания. ## Эхо-сообщение прочитано ### Запрос Сопоставляйте с событием создания по id или wamid. События обновления не содержат текст и тип сообщения. ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "id": "evt_example_echo_read", "type": "whatsapp.echo_message.updated", "apiVersion": "v2", "createTime": "2026-09-09T02:00:03.000Z", "whatsappMessage": { "id": "MESSAGE_ID", "wamid": "wamid.EXAMPLE", "wabaId": "WABA_ID", "from": "+12025550123", "to": "+12025550124", "recipientUserId": "GB.898232076600896", "status": "read", "updateTime": "2026-09-09T02:00:02.000Z", "readTime": "2026-09-09T02:00:02.000Z" } } ``` ### Ответ ```http theme={"theme":{"light":"github-light","dark":"github-dark"}} HTTP/1.1 200 OK ``` ### Пояснение Зафиксируйте переход в статус прочтения, используя `updateTime` и `readTime` в качестве времени исходного события. ## Запоздалый статус отправки после прочтения ### Запрос Исходный статус более низкого ранга может поступить после прочтения. Зафиксируйте событие, не понижая текущий статус сообщения. ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "id": "evt_example_echo_sent", "type": "whatsapp.echo_message.updated", "apiVersion": "v2", "createTime": "2026-09-09T02:00:03.000Z", "whatsappMessage": { "id": "MESSAGE_ID", "wamid": "wamid.EXAMPLE", "wabaId": "WABA_ID", "from": "+12025550123", "to": "+12025550124", "recipientUserId": "GB.898232076600896", "status": "sent", "updateTime": "2026-09-09T02:00:00.000Z", "sendTime": "2026-09-09T02:00:00.000Z" } } ``` ### Ответ ```http theme={"theme":{"light":"github-light","dark":"github-dark"}} HTTP/1.1 200 OK ``` ### Пояснение Сохраните это событие в истории доставки, но не понижайте более поздний текущий статус, такой как `read`. ## Ошибка эхо-сообщения ### Запрос Это отдельное сообщение с ошибкой, а не переход из статуса прочтения. Обновления со сбоем содержат сведения об исходной ошибке, если они доступны. ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "id": "evt_example_echo_failed", "type": "whatsapp.echo_message.updated", "apiVersion": "v2", "createTime": "2026-09-09T02:00:03.000Z", "whatsappMessage": { "id": "FAILED_MESSAGE_ID", "wamid": "wamid.FAILED_EXAMPLE", "wabaId": "WABA_ID", "from": "+12025550123", "to": "+12025550124", "recipientUserId": "GB.898232076600896", "status": "failed", "errorCode": "131000", "errorMessage": "Provider failure", "updateTime": "2026-09-09T02:00:03.000Z" } } ``` ### Ответ ```http theme={"theme":{"light":"github-light","dark":"github-dark"}} HTTP/1.1 200 OK ``` ### Пояснение Используйте `errorCode` и `errorMessage` для диагностики, когда исходный обратный вызов предоставляет их. ### Связанные примеры * [Создание эхо-сообщения WhatsApp](/ru/api-reference/guides/examples/webhook-examples/whatsapp-echo-message-created) * [Обновление передачи агенту в WhatsApp](/ru/api-reference/guides/examples/webhook-examples/whatsapp-meta-business-agent-handover-updated) * [Примеры эхо-сообщений и передачи агенту](/ru/api-reference/guides/examples/webhook-examples/overview#echo-and-agent-handover-events) * [Полный каталог полезных нагрузок](/ru/api-reference/guides/examples/webhook-examples/webhook-payload-examples) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.