AccediInizia la prova gratuita
Meta Tech Provider

Perché un messaggio WhatsApp non è stato consegnato: leggere lo stato failed e i relativi errori

Un webhook di stato failed indica che Meta non ha potuto inviare o consegnare un messaggio inviato dall'azienda tramite l'API. Arriva sul campo messages con valore status failed e un array errors che contiene code, title, message, error_data.details e href. Il code indica il motivo: 131047 finestra chiusa, 131026 non consegnabile, 131049 limite marketing, 131050 marketing interrotto, 131042 problema di pagamento.

easyCoexistence collega il tuo numero dell'app WhatsApp Business all'API Cloud di Meta tramite Coexistence e inoltra gli stati failed al tuo server, direttamente o come inoltri firmati quando le automazioni sono attive.

131047

Sono passate più di 24 ore dall'ultima risposta del destinatario; la soluzione di Meta è inviare un template.

131049

Non consegnato per tutelare il coinvolgimento dell'ecosistema; attendi almeno 24 ore prima di reinviare il template marketing.

131050

Il destinatario ha scelto di interrompere i messaggi di marketing dell'azienda; Meta indica di non riprovare.

No contacts

Uno stato failed non include l'array contacts, quindi collega il fallimento tramite statuses.id.

Delivered

Meta addebita i messaggi quando vengono consegnati, non quando vengono inviati.

Com'è fatto uno stato failed?

Come ogni stato, con in più errors. Manca l'array contacts, recipient_user_id è omesso quando il messaggio è stato inviato a un numero di telefono, e non c'è alcun oggetto pricing. title e message riportano lo stesso testo, error_data.details lo spiega in una frase e href punta alla lista dei codici di errore di Meta. Questo è l'esempio ufficiale di Meta, un template di marketing bloccato dal limite per utente:

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

Quali codici di errore compaiono più spesso e cosa significano?

Meta restituisce errori nella risposta di invio, in uno stato failed, o in entrambi, quindi lo stesso codice può arrivarti in entrambi i modi e il tuo handler deve leggere entrambi i punti. Questi sono i codici che spiegano la maggior parte dei messaggi che non arrivano, con il motivo di Meta e la prima cosa da provare; la lista completa si trova nel riferimento dei codici di errore di 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.

Come deve reagire un handler a ogni tipo di errore?

Classifica il codice in base a cosa fare dopo, prima di qualsiasi nuovo tentativo. Un nuovo tentativo generico trasforma una disiscrizione dai messaggi di marketing in fallimenti ripetuti e può prolungare un blocco, mentre scartare un errore temporaneo fa perdere un messaggio che sarebbe partito un minuto dopo.

  • Riprova con backoff: 131000 sconosciuto, 131016 servizio non disponibile, 130429 throughput raggiunto.
  • Attendi prima: 131049, almeno 24 ore, perché i tentativi precoci possono bloccare quell'utente per altre 24 ore.
  • Cambia messaggio: 131047 richiede un template approvato, perché la finestra di 24 ore è chiusa.
  • Fermati per questo cliente: 131050, finché non arriva un user_preferences resume.
  • Correggi account o contenuto: 131042 pagamento, 131031 account limitato, 131053 media.

Quali errori compaiono solo come stato failed?

Quelli che Meta decide dopo aver accettato la richiesta. L'invio restituisce un wamid, e il rifiuto arriva dopo su questo webhook. Meta non consegna i template di marketing agli utenti WhatsApp con numeri di telefono degli Stati Uniti (+1 con prefisso di area USA); un template di marketing inviato a un cliente che ha interrotto i messaggi di marketing viene elaborato e poi segnalato come failed con 131050, e il limite di marketing per utente segnala 131049 allo stesso modo.

Se il numero non ha una destinazione webhook, questi errori non finiscono in nessun posto visibile e il messaggio sembra semplicemente inviato. Per l'ordine completo dei controlli quando un cliente non ha ricevuto nulla, vedi la pagina sui messaggi WhatsApp API non consegnati.

Cosa cambia su un numero Coexistence?

Due cose contano. Primo, la finestra di 24 ore vale solo per l'API. La guida Coexistence di Meta dice che i messaggi inviati dall'app WhatsApp Business non sono soggetti alla finestra di assistenza clienti, quindi dopo un 131047 il titolare può rispondere a quel cliente dal telefono, mentre il tuo sistema invia un template approvato.

Secondo, il throughput è fisso. Un numero usato contemporaneamente nell'app e nell'API invia al massimo 20 messaggi al secondo, e superare questo valore restituisce 130429. Tutto il resto si legge come su qualsiasi numero Cloud API: stesso campo, stesso array errors, stessi codici.

Come vedono un fallimento automazioni e la tua AI?

Dipende da quando Meta dice no. Un rifiuto al momento dell'invio, come 131047, fa fallire il passaggio dell'automazione: l'esecuzione mostra Failed con il messaggio di Meta nella scheda Runs, e il titolare riceve un'email per rispondere lui stesso al cliente. Le automazioni controllano anche la finestra prima di inviare una risposta a testo libero e saltano con window_closed invece di tentare.

Un fallimento che Meta segnala dopo arriva come stato failed al tuo Forward URL o alla destinazione diretta, e l'esecuzione resta com'è. Un'AI che ha inviato un template tramite il connettore MCP vede il wamid e "sent: true"; chiedi al tuo sistema lo stato di quel wamid, oppure fai eseguire all'assistente get_number_health quando molti messaggi falliscono insieme.

Errori comuni

  • Riprovare 131050 in un ciclo. Il cliente ha interrotto i messaggi di marketing, quindi ogni tentativo fallisce allo stesso modo finché non riattiva.
  • Reinviare un template di marketing 131049 dopo poche ore. Meta chiede almeno 24 ore, e i tentativi precoci possono bloccare quell'utente per altre 24 ore.
  • Registrare solo il title. error_data.details contiene il motivo specifico, quindi salva codice e dettagli insieme al wamid.
  • Operare senza una destinazione webhook e giudicare la consegna dalla risposta di invio, che dice solo che Meta ha accettato il messaggio.
Farlo con EasyCoexistence

Quando la risposta di un'automazione viene rifiutata al momento dell'invio, l'esecuzione mostra l'errore di Meta e ricevi un'email, e ogni numero è monitorato 24/7 per disconnessioni e cali di qualità. Da US$ 9 a US$ 0,75 per numero al mese, e il prezzo scende man mano che aggiungi numeri, con i primi 3 giorni di prova gratuita.

Domande frequenti

È un messaggio fallito addebitato da Meta?

Le pagine prezzi di Meta dicono che addebita i messaggi consegnati, non quelli solo inviati. Uno stato failed non contiene alcun oggetto pricing. Gli addebiti vanno all'account WhatsApp Business dell'azienda; easyCoexistence non applica alcun ricarico.

Il 131026 significa che il cliente ha bloccato l'azienda?

La lista di Meta per 131026 indica altri motivi: il numero non è su WhatsApp, il destinatario non ha accettato gli ultimi termini, oppure la sua versione di WhatsApp è troppo vecchia. Meta suggerisce di chiedere al cliente, tramite un altro canale, di verificare questi punti.

Perché recipient_user_id compare in alcuni fallimenti e in altri no?

Meta lo omette in uno stato failed quando il messaggio è stato inviato a un numero di telefono. Quando hai inviato al BSUID del cliente, il fallimento lo include, e può mancare recipient_id.

Un messaggio può fallire dopo essere stato consegnato?

Il riferimento di Meta descrive failed come un errore di invio o consegna. Una volta che il messaggio ha raggiunto il dispositivo, gli stati successivi attesi sono read, oppure played per i messaggi vocali.

Continua a leggere

Pronto per iniziare?

Configura WhatsApp Coexistence in pochi minuti, non in mesi. L'app continua a funzionare sul telefono.

Inizia la prova gratuita

Verificato il