Conectați-văÎncepeți perioada de probă gratuită
Meta Tech Provider

De ce a eșuat un mesaj WhatsApp: citirea statusului failed și a erorilor

Un webhook cu status failed înseamnă că Meta nu a putut trimite sau livra un mesaj trimis de afacere prin API. Ajunge pe câmpul messages, cu status failed și un array errors care conține code, title, message, error_data.details și href. Codul indică motivul: 131047 fereastră închisă, 131026 nelivrabil, 131049 limita de marketing, 131050 marketing oprit, 131042 problemă de plată.

easyCoexistence conectează numărul din aplicația WhatsApp Business la Cloud API prin Coexistence și transmite statusurile failed către propriul server, direct sau ca redirecționări semnate când automatizările sunt active.

131047

Au trecut peste 24 de ore de la ultimul răspuns al destinatarului; soluția Meta este trimiterea unui template.

131049

Nelivrat, pentru a menține sănătoasă implicarea din ecosistem; așteptați cel puțin 24 de ore înainte de a retrimite template-ul de marketing.

131050

Destinatarul a ales să oprească mesajele de marketing de la afacere; Meta spune să nu reîncercați.

No contacts

Un status failed nu conține array-ul contacts, deci corelați eșecul prin statuses.id.

Delivered

Meta taxează mesajele livrate, nu pe cele doar trimise.

Cum arată un status failed?

Ca orice status, plus errors. Lipsește array-ul contacts, recipient_user_id nu apare când mesajul a fost trimis unui număr de telefon, iar nu există obiectul pricing. title și message conțin același text, error_data.details explică într-o propoziție, iar href indică lista de coduri de eroare a Meta. Acesta este exemplul oficial al Meta, un template de marketing oprit de limita per utilizator:

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

Ce coduri de eroare apar cel mai des și ce înseamnă?

Meta returnează erori în răspunsul la trimitere, într-un status failed sau în ambele, deci același cod vă poate ajunge pe oricare cale, iar handler-ul trebuie să citească ambele locuri. Acestea sunt codurile care explică majoritatea mesajelor care nu ajung, cu motivul dat de Meta și primul lucru de încercat; lista completă se află în referința de coduri de eroare a 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.

Cum trebuie să reacționeze un handler la fiecare tip de eșec?

Clasificați codul în ce urmează înainte ca orice reîncercare să pornească. O reîncercare generală transformă un refuz de marketing în eșecuri repetate și poate prelungi un blocaj, în timp ce renunțarea la o eroare temporară pierde un mesaj care ar fi trecut un minut mai târziu.

  • Reîncercați cu backoff: 131000 necunoscută, 131016 serviciu indisponibil, 130429 limita de debit atinsă.
  • Așteptați mai întâi: 131049, cel puțin 24 de ore, deoarece reîncercările devreme pot bloca acel utilizator încă până la 24 de ore.
  • Schimbați mesajul: 131047 necesită un template aprobat, pentru că fereastra de 24 de ore este închisă.
  • Opriți pentru acest client: 131050, până când sosește un user_preferences resume.
  • Reparați contul sau conținutul: 131042 plată, 131031 cont restricționat, 131053 media.

Ce eșecuri apar doar ca status failed?

Cele pe care Meta le decide după ce a acceptat cererea. Trimiterea returnează un wamid, iar refuzul vine mai târziu pe acest webhook. Meta nu livrează template-urile de marketing către utilizatorii WhatsApp cu numere de telefon din Statele Unite (+1 cu prefix de zonă american). Un template de marketing către un client care a oprit mesajele de marketing este procesat și apoi raportat ca failed cu 131050, iar limita de marketing per utilizator raportează 131049 în același mod.

Dacă numărul nu are o destinație de webhook, aceste eșecuri nu ajung nicăieri vizibil, iar mesajul pare doar trimis. Pentru ordinea completă a verificărilor când un client nu a primit nimic, consultați pagina despre mesajele WhatsApp API nelivrate.

Ce se schimbă pe un număr Coexistence?

Două lucruri contează. Primul: fereastra de 24 de ore se aplică doar API-ului. Ghidul Coexistence al Meta spune că mesajele trimise din aplicația WhatsApp Business nu sunt supuse ferestrei serviciului pentru clienți, deci după un 131047 proprietarul poate răspunde în continuare acelui client de pe telefon, în timp ce sistemul trimite un template aprobat.

Al doilea: debitul este fix. Un număr folosit simultan în aplicație și în API trimite cel mult 20 de mesaje pe secundă, iar depășirea returnează 130429. Restul se citește la fel ca pe orice număr Cloud API: același câmp, același array errors, aceleași coduri.

Cum văd automatizările și AI-ul un eșec?

Depinde de momentul în care Meta spune nu. Un refuz la trimitere, cum este 131047, oprește pasul automatizării: rularea apare ca Failed cu mesajul Meta în fila Runs, iar proprietarul primește un e-mail ca să răspundă singur clientului. Automatizările verifică și fereastra înainte de un răspuns liber și sar peste cu window_closed în loc să încerce.

Un eșec raportat de Meta ulterior ajunge ca status failed la Forward URL sau la destinația directă, iar rularea rămâne neschimbată. Un AI care a trimis un template prin conectorul MCP vede wamid-ul și „sent: true”; cereți sistemului statusul acelui wamid sau cereți asistentului să ruleze get_number_health când eșuează multe mesaje deodată.

Greșeli frecvente

  • Reîncercarea 131050 în buclă. Clientul a oprit mesajele de marketing, deci fiecare încercare eșuează la fel până când clientul reia mesajele.
  • Retrimiterea unui template de marketing 131049 în câteva ore. Meta cere cel puțin 24 de ore, iar reîncercările devreme pot bloca acel utilizator încă până la 24 de ore.
  • Înregistrarea doar a titlului. error_data.details conține motivul specific, deci salvați codul și detaliile împreună cu wamid-ul.
  • Rularea fără destinație de webhook și judecarea livrării după răspunsul la trimitere, care spune doar că Meta a acceptat mesajul.
Faceți acest lucru cu EasyCoexistence

Când un răspuns al automatizării este refuzat la trimitere, rularea arată eroarea Meta și primiți un e-mail, iar fiecare număr este monitorizat non-stop pentru deconectări și scăderi de calitate. US$ 9 până la US$ 0,75 pe număr pe lună, scăzând pe măsură ce adăugați numere, cu primele 3 zile gratuite.

Întrebări frecvente

Taxează Meta un mesaj eșuat?

Paginile de prețuri ale Meta spun că taxează mesajele livrate, nu cele doar trimise. Un status failed nu conține obiect de preț. Costurile merg în contul WhatsApp Business al afacerii; easyCoexistence nu aplică niciodată un adaos.

Înseamnă 131026 că clientul a blocat afacerea?

Lista Meta pentru 131026 numește și alte motive: numărul nu este pe WhatsApp, destinatarul nu a acceptat ultimii termeni sau versiunea sa de WhatsApp este prea veche. Meta recomandă să verificați acestea cerându-i clientului printr-un alt canal.

De ce apare recipient_user_id la unele eșecuri și la altele nu?

Meta îl omite la un status failed când mesajul a fost trimis unui număr de telefon. Când ați trimis către BSUID-ul clientului, eșecul îl include, iar recipient_id poate fi cel lipsă.

Poate un mesaj să eșueze după ce a fost livrat?

Referința Meta descrie failed ca un eșec la trimitere sau livrare. Odată ce mesajul a ajuns pe dispozitiv, următoarele statusuri așteptate sunt read sau played, pentru mesajele vocale.

Continuați să citiți

Gata să începeți?

Configurați WhatsApp Coexistence în câteva minute, nu luni. Aplicația continuă să funcționeze pe telefon.

Începeți perioada de probă gratuită

Verificat la