Zaloguj sięRozpocznij bezpłatny okres próbny
Meta Tech Provider

Dlaczego wiadomość WhatsApp nie została dostarczona: status failed i jego błędy

Webhook ze statusem failed oznacza, że Meta nie mogła wysłać ani dostarczyć wiadomości wysłanej przez firmę przez API. Trafia do pola messages ze statusem failed i tablicą errors zawierającą code, title, message, error_data.details oraz href. Kod podaje przyczynę: 131047 zamknięte okno, 131026 wiadomość niedostarczalna, 131049 limit wiadomości marketingowych, 131050 marketing zatrzymany, 131042 problem z płatnością.

easyCoexistence łączy numer z aplikacją WhatsApp Business z Cloud API Meta przez Coexistence i przekazuje statusy failed na Twój serwer, bezpośrednio lub jako podpisane przekierowania, gdy automatyzacje są włączone.

131047

Minęło ponad 24 godziny od ostatniej odpowiedzi odbiorcy; zalecenie Meta to wysłać szablon.

131049

Nie dostarczono, aby utrzymać zdrowe zaangażowanie w ekosystemie; przed ponownym wysłaniem szablonu marketingowego odczekaj co najmniej 24 godziny.

131050

Odbiorca zdecydował się zatrzymać wiadomości marketingowe od firmy; Meta zaleca nie ponawiać.

No contacts

Status failed nie zawiera tablicy contacts, więc powiąż błąd przez statuses.id.

Delivered

Meta pobiera opłaty za wiadomości dostarczone, a nie za wysłane.

Jak wygląda status failed?

Jak każdy status, plus errors. Tablica contacts jest pominięta, recipient_user_id jest pomijany, gdy wiadomość wysłano na numer telefonu, a obiekt pricing nie występuje. title i message zawierają ten sam tekst, error_data.details wyjaśnia go jednym zdaniem, a href wskazuje listę kodów błędów Meta. To przykład podany przez samą Meta: szablon marketingowy zatrzymany przez limit na użytkownika:

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

Które kody błędów wracają najczęściej i co oznaczają?

Meta zwraca błędy w odpowiedzi na wysłanie, w statusie failed albo w obu miejscach, więc ten sam kod może dotrzeć dowolną drogą, a handler powinien czytać oba. Poniżej kody, które tłumaczą większość wiadomości, które nigdy nie docierają, z powodem podanym przez Meta i pierwszą rzeczą do sprawdzenia; pełna lista znajduje się w dokumentacji kodów błędów 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.

Jak handler powinien reagować na każdy rodzaj błędu?

Najpierw przypisz kod do następnego kroku, zanim cokolwiek zostanie ponowione. Ślepe ponawianie zamienia rezygnację z marketingu w powtarzające się błędy i może wydłużyć blokadę, a pominięcie błędu tymczasowego gubi wiadomość, która przeszłaby minutę później:

  • Ponów z opóźnieniem (backoff): 131000 nieznany, 131016 usługa niedostępna, 130429 osiągnięto przepustowość.
  • Najpierw poczekaj: 131049, co najmniej 24 godziny, bo wczesne ponowienia mogą zablokować tego użytkownika na kolejne 24 godziny.
  • Zmień sposób wysyłki: 131047 wymaga zatwierdzonego szablonu, ponieważ 24-godzinne okno jest zamknięte.
  • Zatrzymaj dla tego klienta: 131050, dopóki nie nadejdzie zdarzenie user_preferences z wznowieniem.
  • Napraw konto lub treść: 131042 płatność, 131031 konto ograniczone, 131053 multimedia.

Które błędy pojawiają się wyłącznie jako status failed?

Te, które Meta rozstrzyga po przyjęciu żądania. Wysyłka zwraca wamid, a odmowa przychodzi później w tym webhooku. Meta nie dostarcza szablonów marketingowych do użytkowników WhatsApp z numerami telefonów w Stanach Zjednoczonych (+1 z amerykańskim kodem obszaru); szablon marketingowy wysłany do klienta, który zrezygnował z wiadomości marketingowych, jest przetwarzany, a następnie zgłaszany jako failed z kodem 131050, a limit na użytkownika zgłasza 131049 w ten sam sposób.

Jeśli numer nie ma miejsca docelowego webhooka, te błędy nie trafią nigdzie, co widać, a wiadomość po prostu wygląda na wysłaną. Pełną kolejność sprawdzeń, gdy klient niczego nie dostał, opisuje strona o wiadomościach API WhatsApp, które nie zostały dostarczone.

Co się zmienia na numerze Coexistence?

Liczą się dwie rzeczy. Po pierwsze, 24-godzinne okno dotyczy wyłącznie API. Przewodnik Meta po Coexistence mówi, że wiadomości wysłane z aplikacji WhatsApp Business nie podlegają oknu obsługi klienta, więc po błędzie 131047 właściciel nadal może odpowiedzieć klientowi z telefonu, podczas gdy Twój system wysyła zatwierdzony szablon.

Po drugie, przepustowość jest stała. Numer używany jednocześnie w aplikacji i w API wysyła co najwyżej 20 wiadomości na sekundę, a przekroczenie tego progu zwraca 130429. Wszystko inne wygląda jak na każdym numerze Cloud API: to samo pole, ta sama tablica errors, te same kody.

Jak automatyzacje i Twoje AI widzą błąd?

Zależy od tego, kiedy Meta odmawia. Odmowa w momencie wysyłki, np. 131047, przerywa krok automatyzacji: przebieg pokazuje status Failed z komunikatem Meta w zakładce Runs, a właściciel dostaje e-mail, by mógł sam odpowiedzieć klientowi. Automatyzacje sprawdzają też okno przed wysłaniem wolnej odpowiedzi i pomijają wysyłkę z window_closed zamiast próbować.

Błąd zgłoszony przez Meta później trafia jako status failed na Twój adres Forward URL lub bezpośredni cel, a przebieg pozostaje bez zmian. AI, które wysłało szablon przez konektor MCP, widzi wamid i „sent: true”; poproś system o status tego wamid albo zleć asystentowi uruchomienie get_number_health, gdy wiele wiadomości kończy się błędem naraz.

Typowe błędy

  • Ponawianie 131050 w pętli. Klient zrezygnował z wiadomości marketingowych, więc każda próba kończy się tym samym błędem, dopóki klient sam tego nie zmieni.
  • Ponowne wysłanie szablonu marketingowego 131049 po kilku godzinach. Meta prosi o co najmniej 24 godziny, a wczesne ponowienia mogą zablokować tego użytkownika na kolejne 24 godziny.
  • Zapisywanie tylko title. error_data.details zawiera konkretny powód, więc zapisuj kod i szczegóły razem z wamid.
  • Działanie bez miejsca docelowego webhooka i ocena dostarczenia na podstawie odpowiedzi na wysłanie, która mówi tylko, że Meta przyjęła wiadomość.
Z EasyCoexistence zrobisz to

Gdy odpowiedź automatyzacji zostanie odrzucona w momencie wysyłki, przebieg pokazuje błąd Meta i dostajesz e-mail, a każdy numer jest monitorowany 24/7 pod kątem rozłączeń i spadków jakości. Od US$ 9 do US$ 0.75 za numer miesięcznie, cena spada wraz z dodawaniem numerów, z pierwszymi 3 dniami za darmo.

Najczęściej zadawane pytania

Czy Meta pobiera opłatę za nieudaną wiadomość?

Strony cenowe Meta mówią, że pobiera opłaty za wiadomości dostarczone, a nie za te, które są tylko wysłane. Status failed nie zawiera obiektu pricing. Opłaty trafiają na konto WhatsApp Business Account należące do firmy; easyCoexistence nie dolicza do nich żadnej marży.

Czy 131026 oznacza, że klient zablokował firmę?

Lista Meta dla 131026 wymienia inne przyczyny: numeru nie ma w WhatsApp, odbiorca nie zaakceptował najnowszych warunków albo jego wersja WhatsApp jest za stara. Meta radzi zapytać klienta innym kanałem, by to sprawdzić.

Dlaczego recipient_user_id pojawia się w niektórych błędach, a w innych nie?

Meta pomija go w statusie failed, gdy wiadomość wysłano na numer telefonu. Gdy wysłano na BSUID klienta, błąd go zawiera, a może brakować recipient_id.

Czy wiadomość może się nie udać po dostarczeniu?

Dokumentacja Meta opisuje failed jako błąd wysłania lub dostarczenia. Gdy wiadomość dotrze na urządzenie, kolejne statusy, jakich można się spodziewać, to read, a przy wiadomościach głosowych played.

Czytaj dalej

Gotowy, aby zacząć?

Skonfiguruj WhatsApp Coexistence w kilka minut, nie miesięcy. Aplikacja nadal działa na telefonie.

Rozpocznij bezpłatny okres próbny

Zweryfikowano w