ВойтиНачать бесплатный пробный период
Meta Tech Provider

Почему сообщение WhatsApp не доставлено: чтение статуса failed и его ошибок

Вебхук со статусом failed означает, что Meta не смогла отправить или доставить сообщение, которое бизнес отправил через API. Он приходит в поле messages со статусом failed и массивом errors, где есть code, title, message, error_data.details и href. Код объясняет причину: 131047 окно обслуживания закрыто, 131026 доставка невозможна, 131049 лимит маркетинговых сообщений, 131050 маркетинговые сообщения остановлены, 131042 проблема с оплатой.

easyCoexistence подключает номер вашего приложения WhatsApp Business к Cloud API Meta через Coexistence и передаёт статусы failed на ваш сервер напрямую или как подписанные пересылки, когда включены автоматизации.

131047

Прошло больше 24 часов с последнего ответа получателя. Исправление от Meta: отправить шаблон вместо обычного сообщения.

131049

Не доставлено, чтобы сохранить здоровую вовлечённость экосистемы. Подождите не меньше 24 часов, прежде чем повторно отправлять маркетинговый шаблон.

131050

Получатель отказался от маркетинговых сообщений этого бизнеса. Meta советует не повторять отправку.

No contacts

В статусе failed нет массива contacts, поэтому сопоставляйте сбой через statuses.id.

Delivered

Meta берёт плату за доставленные сообщения, а не за отправленные.

Как выглядит статус failed?

Как и любой другой статус, но с массивом errors. Массива contacts нет, recipient_user_id отсутствует, если сообщение отправлено на номер телефона, и объекта pricing тоже нет. title и message содержат один и тот же текст, error_data.details объясняет его одним предложением, а href ведёт к списку кодов ошибок Meta. Ниже пример самой Meta: маркетинговый шаблон остановлен лимитом на пользователя:

Meta's example: a message that failed with 131049
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI0QUQ2MjA4NEYyRkExNjMyREUA",
                "status": "failed",
                "timestamp": "1751142888",
                "recipient_id": "16505551234",
                "errors": [
                  {
                    "code": 131049,
                    "title": "This message was not delivered to maintain healthy ecosystem engagement.",
                    "message": "This message was not delivered to maintain healthy ecosystem engagement.",
                    "error_data": {
                      "details": "In order to maintain a healthy ecosystem engagement, the message failed to be delivered."
                    },
                    "href": "/documentation/business-messaging/whatsapp/support/error-codes"
                  }
                ]
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Какие коды ошибок приходят чаще всего и что они значат?

Meta возвращает ошибки в ответе на отправку, в статусе failed или в обоих местах, поэтому один и тот же код может прийти любым путём, и обработчик должен смотреть в оба места. Ниже коды, которые объясняют большинство сообщений, так и не дошедших до получателя: причина от Meta и первое действие. Полный список находится в справочнике кодов ошибок Meta:

131026Undeliverable: not a WhatsApp number, terms not accepted, or an outdated WhatsApp version on the recipient's phone.
131047More than 24 hours since the customer last wrote. Send an approved template instead.
131049Held back to keep engagement healthy, usually the per-user marketing limit. Wait 24 hours or more.
131050The customer stopped marketing messages from you. Do not retry.
131042A problem with the payment method on the WhatsApp Business Account.
130472Not sent because the recipient is part of Meta's marketing message experiment.
131053Media could not be uploaded, often an unsupported file type.
131000Unknown error. Try again; if it persists, open a Direct Support ticket.

Как обработчику реагировать на каждый тип сбоя?

Сначала разделите код по следующему действию, и только потом что-то повторяйте. Слепой повтор превращает отказ от маркетинга в серию сбоев и может продлить блокировку, а сброс временной ошибки теряет сообщение, которое прошло бы через минуту.

  • Повтор с нарастающей паузой: 131000 неизвестная ошибка, 131016 сервис недоступен, 130429 достигнут лимит пропускной способности.
  • Сначала подождите: 131049, не меньше 24 часов, так как ранние повторы могут заблокировать этого пользователя ещё на 24 часа.
  • Переключите сообщение: 131047 требует одобренного шаблона, потому что окно обслуживания клиентов в 24 часа закрыто.
  • Остановите отправку этому клиенту: 131050, пока не придёт событие user_preferences с resume.
  • Исправьте аккаунт или содержимое: 131042 оплата, 131031 аккаунт ограничен, 131053 медиа.

Какие сбои видны только в статусе failed?

Те, которые Meta решает уже после принятия запроса. Отправка возвращает wamid, а отказ приходит позже, в этом вебхуке. Meta не доставляет маркетинговые шаблоны пользователям WhatsApp с номерами США (+1 с американским кодом региона). Маркетинговый шаблон клиенту, который отказался от маркетинга, обрабатывается и затем помечается как failed с кодом 131050, а лимит маркетинговых сообщений на пользователя так же возвращает 131049.

Если у номера нет адреса для вебхука, такие сбои никуда не попадают, и сообщение просто выглядит отправленным. Полный порядок проверок, когда клиент ничего не получил, описан на странице «Сообщения WhatsApp API, которые не доставлены».

Что меняется на номере Coexistence?

Важны две вещи. Во-первых, окно обслуживания клиентов в 24 часа действует только для API. По руководству Meta по Coexistence, сообщения, отправленные из приложения WhatsApp Business, не подпадают под это окно, поэтому после 131047 владелец всё ещё может ответить этому клиенту с телефона, пока ваша система отправляет одобренный шаблон.

Во-вторых, пропускная способность фиксирована. Номер, который одновременно работает в приложении и в API, отправляет не более 20 сообщений в секунду, а превышение возвращает 130429. Во всём остальном он устроен так же, как любой номер Cloud API: то же поле, тот же массив errors и те же коды.

Как автоматизации и ваш ИИ видят сбой?

Всё зависит от того, когда Meta отказывает. Отказ на этапе отправки, например 131047, проваливает шаг автоматизации: в журнале запуска (вкладка Runs) появляется Failed с сообщением Meta, а владелец получает письмо, чтобы ответить клиенту самому. Автоматизации также проверяют окно перед свободным ответом и пропускают отправку с window_closed, а не пытаются отправить.

Сбой, о котором Meta сообщает позже, приходит как статус failed на Forward URL или прямой адрес, а запуск остаётся таким, каким был. ИИ, который отправил шаблон через MCP-коннектор, видит wamid и «sent: true». Попросите систему запросить статус этого wamid или поручите ассистенту выполнить get_number_health, если сразу много сообщений не доходит.

Распространённые ошибки

  • Повтор 131050 в цикле. Клиент отказался от маркетинговых сообщений, поэтому каждая попытка заканчивается тем же сбоем, пока он не возобновит подписку.
  • Повторная отправка маркетингового шаблона 131049 в течение нескольких часов. Meta просит подождать не меньше 24 часов, а ранние повторы могут заблокировать этого пользователя ещё на 24 часа.
  • Логирование только title. error_data.details содержит конкретную причину, поэтому сохраняйте code и details вместе с wamid.
  • Работа без адреса для вебхука и оценка доставки по ответу на отправку, который лишь говорит, что Meta приняла сообщение.
Настройка с EasyCoexistence

Если ответ автоматизации отклонён на этапе отправки, запуск показывает ошибку Meta, а вы получаете письмо. Каждый номер круглосуточно отслеживается на отключения и падение качества. От US$ 9 за подключённый номер в месяц до US$ 0,75 по мере добавления номеров, с бесплатным пробным периодом 3 дня.

Часто задаваемые вопросы

Meta берёт плату за сообщение со статусом failed?

Страницы Meta о ценах говорят, что плата берётся за доставленные сообщения, а не за те, что только отправлены. В статусе failed нет объекта pricing. Списания идут на WhatsApp Business Account бизнеса, а easyCoexistence никогда не добавляет наценку.

Означает ли 131026, что клиент заблокировал бизнес?

Список Meta для 131026 называет другие причины: номера нет в WhatsApp, получатель не принял последние условия или у него слишком старая версия WhatsApp. Meta советует уточнить это у клиента через другой канал.

Почему recipient_user_id есть в одних сбоях и нет в других?

Meta не включает его в статус failed, когда сообщение отправлено на номер телефона. Если вы отправляли на BSUID клиента, сбой содержит его, а может отсутствовать recipient_id.

Может ли сообщение завершиться сбоем после доставки?

В справочнике Meta статус failed означает сбой отправки или доставки. Если сообщение уже дошло до устройства, дальше ожидаются статусы read, а для голосовых сообщений played.

Читайте дальше

Статусы вебхуков WhatsApp: отправлено, доставлено, прочитано, ошибкаКак WhatsApp сообщает о судьбе отправленного сообщения: массив statuses, значения статусов, поля и сопоставление по wamid.Вебхук user_preferences: когда клиент отключает или возобновляет маркетинговые сообщенияВебхук user_preferences срабатывает, когда клиент останавливает или возобновляет маркетинговые сообщения. Формат данных, действия и сигнал 131050.Сообщение WhatsApp API не доставлено: причины в порядке проверкиСообщение WhatsApp API не приходит: статус вебхука, окно 24 часа, оплата, шаблоны, получатель и лимиты, в порядке, который находит причину.Шаблон WhatsApp на паузе или отключён: что делатьНизкокачественный шаблон WhatsApp ставится на паузу на 3 часа, затем на 6, после чего отключается. Как понять и что делать дальше.Ошибка WhatsApp 131049: сообщение заблокировано для здоровья экосистемыОшибка 131049 означает, что Meta заблокировала отправку для защиты экосистемы, а не из-за закрытия окна 24 часа. Почему шаблон не поможет.Окно обслуживания клиентов на 24 часаЧто такое окно обслуживания клиентов, когда оно открывается и закрывается, что можно отправлять внутри и вне него и почему ответы внутри бесплатны.

Готовы начать?

Настройте WhatsApp Coexistence за несколько минут, а не месяцев. Приложение продолжит работать на телефоне.

Начать бесплатный пробный период

Проверено по состоянию на