Invii template WhatsApp possono restituire 200 ma non arrivare al cliente

Un template WhatsApp può restituire 200 e un message ID, ma il messaggio non arriva al cliente¹.

La POST a /<PHONE_NUMBER_ID>/messages conferma che la piattaforma ha accettato la richiesta. La consegna si verifica dopo, via webhook di stato: sent, delivered, read oppure failed con un array di errors. Gli errori possono emergere nella risposta immediata, nel webhook, o in entrambi. Tra richiesta e webhook resta uno spazio in cui i fallimenti non si vedono¹.

In produzione questo vuoto conta. Gli autori riportano tre cause osservate. Media inviati come link che il sistema non riesce a scaricare, quindi il messaggio non parte. Parametri non allineati al template, con conteggi che non tornano. Pulsante copy‑code senza coupon associato, che rende il template non valido¹.

Il rischio cresce in ambienti locali e di staging. Spesso lì manca il webhook di stato. Ogni invio “riesce” perché la risposta è accepted, ma i messaggi non arrivano e nessuno vede failed. Il problema resta latente fino al passaggio in produzione¹.

Le contromisure sono operative. Costruisci l’evento a partire dalla definizione del template. Valida i parametri obbligatori e il loro numero. Se manca un valore, blocca l’invio. Per i media, non passare link remoti: usa l’ID di un upload già presente. Tratta accepted come non confermato. Considera concluso l’invio solo quando ricevi lo status atteso dal webhook¹.

Esempio operativo in pseudo‑codice, che segue questo metodo:

• valida i parametri contro la definizione del template;
• preferisce media_id a link;
• invia e attende il webhook prima di marcare successo o fallimento.

Snippet:

function sendTemplateMessage(templateDef, payload):
    // 1) Validazione
    if count(payload.params) != count(templateDef.params):
        return error("parametri non allineati")

    if templateDef.requires_copy_code and not payload.copy_code:
        return error("manca il coupon per il copy-code")

    if payload.media_link and not payload.media_id:
        return error("usa media_id da upload, non un link remoto")

    // 2) Invio
    resp = POST("/<PHONE_NUMBER_ID>/messages", buildBody(templateDef, payload))

    if resp.status != 200:
        return error("errore immediato", resp)

    // 3) Stato asincrono
    savePending(resp.message_id)
    // un consumer del webhook aggiorna lo stato:
    // onWebhook(event): updateStatus(event.message_id, event.status, event.errors)

    return ok("richiesta accettata, in attesa di webhook", resp.message_id)

“Accepted non è delivered” merita una sola regola chiara: finché non arriva uno status, l’esito resta incerto. L’osservabilità passa dal webhook di stato, dove compaiono sent, delivered, read e failed con l’array di errors. Senza quel canale, i fallimenti silenti restano fuori vista e fuorviano i test, specie fuori dalla produzione¹.

Come testare in staging senza inciampare nel buio: attiva un endpoint di webhook raggiungibile dall’esterno prima di iniziare i test. Collega quel webhook all’app di test. Logga ogni evento di stato con message ID e timestamp. Segna riuscito un invio solo dopo delivered, segna fallito su failed e analizza l’array di errors. Questa routine rende visibili i problemi che la sola risposta 200 non mostra¹.