Notifiche di stato e prezzo

Il client dell'API di WhatsApp Business invia notifiche sullo status del messaggio tra te e i tuoi utenti. Queste notifiche vengono inviate tramite l'oggetto statuses.

Aggiornamenti di stato

Per ogni messaggio inviato dalla tua azienda, riceverai una notifica relativa allo stato corrispondente. Nella tabella sotto, clicca sulla freccia nella colonna di sinistra per l'equivalente nell'app WhatsApp di ogni stato, se disponibile.

Nome	Descrizione
`deleted`	L'utente ha eliminato un messaggio che aveva precedentemente inviato. Dopo aver ricevuto questa notifica, devi assicurarti che il messaggio venga eliminato dal tuo sistema nel caso in cui sia stato scaricato dal server.
Equivalente nell'app WhatsApp	Su WhatsApp mobile, il messaggio viene sostituito con la nota "Questo messaggio è stato eliminato".
`delivered`	Un messaggio inviato dalla tua azienda è stato consegnato al dispositivo dell'utente.
Equivalente nell'app WhatsApp	Due spunte
`failed`	Non è stato possibile inviare un messaggio mandato dalla tua azienda. Il motivo dell'errore sarà incluso nella callback. Controlla la documentazione sui messaggi di errore per aiuto con il debug: Errori dell'API On-Premises Codici di errore dell'API Cloud e Risoluzione dei problemi
Equivalente nell'app WhatsApp	Triangolo di errore rosso
`read`	Un messaggio inviato dalla tua azienda è stato letto dall'utente. `Le notifiche read` sono disponibili solo per gli utenti che hanno abilitato le conferme di lettura. Gli utenti che non le hanno abilitate riceveranno solo la notifica `delivered` .
Equivalente nell'app WhatsApp	Due spunte blu
`sent`	Un messaggio inviato dalla tua azienda è in transito nei nostri sistemi. Per gli utenti dell'API On-Premises: per ricevere notifiche per messaggi `sent` imposta l'impostazione `sent_status` su `true` nelle impostazioni dell'app. La notifica di stato `sent` è disabilitata per impostazione predefinita.
Equivalente nell'app WhatsApp	Una spunta
`warning`	Un messaggio inviato dalla tua azienda contiene un articolo di un catalogo che non è disponibile o che non esiste.

L'ordine di queste notifiche nell'app potrebbe non riflettere gli orari effettivi dello stato del messaggio. Visualizza la marca temporale per determinare l'orario, se necessario.

Perché uno stato sia read, deve essere stato delivered. In alcuni scenari, ad esempio quando un utente si trova nella schermata della chat e arriva un messaggio, il messaggio è delivered e read quasi contemporaneamente. In questo o in altri scenari simili, la notifica delivered non verrà inviata poiché è implicito che se un messaggio è stato letto significa che è stato consegnato. Questo comportamento viene applicato per questioni di ottimizzazione interna.

Aggiornamenti di prezzo

A partire dal 1° febbraio 2022, l'oggetto statuses nelle notifiche in uscita include due nuovi oggetti nidificati: conversation e pricing. I componenti degli oggetti conversation e pricing variano a seconda della modalità di inizio della conversazione. Le conversazioni possono essere avviate dall'utente, dall'azienda o da un punto di accesso gratuito. Scopri altre informazioni di seguito:

Esempi

Nei seguenti esempi, recipient_id potrebbe invece essere un campo group_id. Dipende dal destinatario del messaggio, se si tratta di un individuo o un gruppo.

Stato: messaggio inviato

Il seguente webhook viene ricevuto quando un'azienda invia un messaggio come parte di una conversazione avviata dall'utente (se la conversazione non è iniziata in un punto di accesso gratuito):

{
   "statuses": [{
     "id": "ID",
     "recipient_id": "WHATSAPP_ID",
     "status": "sent",
     "timestamp": "TIMESTAMP",
     "type": "message",
     "message": {         
        "recipient_id":"WHATSAPP_ID"   
     },
     "conversation": {
       "id": "CONVERSATION_ID",
       "expiration_timestamp": TIMESTAMP,
       "origin": {
         "type": "user_initiated"
       }
      },
    "pricing": {
      "pricing_model": "CBP",
      "billable": true,
      "category": "user_initiated"
    }
   }]
}

Il seguente webhook viene ricevuto quando un'azienda invia un messaggio come parte di una conversazione avviata dall'utente per un messaggio multimediale (se la conversazione non è iniziata in un punto di accesso gratuito):

{
   "statuses": [{
     "id": "ID",
     "recipient_id": "WHATSAPP_ID",
     "status": "sent",
     "timestamp": "TIMESTAMP",
     "type": "message",
     "message": {   
       "media_id": "98d14c8e-0310-4061-8f99-2d148274c286",
       "recipient_id":"WHATSAPP_ID"  
     },
     "conversation": {
       "id": "CONVERSATION_ID",
       "expiration_timestamp": TIMESTAMP,
       "origin": {
         "type": "user_initiated"
       }
      },
    "pricing": {
      "pricing_model": "CBP",
      "billable": true,
      "category": "user_initiated"
    }
   }]
}

Il seguente webhook viene ricevuto quando un'azienda invia un messaggio come parte di una conversazione avviata dall'azienda:

{
  "statuses": [{
    "id": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "sent",
    "timestamp": "TIMESTAMP",
    "type": "message",         
    "message": {
        "recipient_id":"WHATSAPP_ID" 
    },
    "conversation": {
      "id": "CONVERSATION_ID",
      "expiration_timestamp": TIMESTAMP,
      "origin": {
         "type": "business_initiated"
      }
    },
    "pricing": {
      "pricing_model": "CBP",
      "billable": true,
      "category": "business_initiated"
    }
   }]
}

Il seguente webhook viene ricevuto quando un'azienda invia un messaggio in risposta a una conversazione avviata dall'utente originata da punti di accesso gratuiti:

{
  "statuses": [{
    "id": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "sent",
    "timestamp": "TIMESTAMP",
    "type": "message",
    "message": {
        "recipient_id":"WHATSAPP_ID"   
    },
    "conversation": {
      "id": "CONVERSATION_ID",
      "expiration_timestamp": TIMESTAMP,
      "origin": {
         "type": "referral_conversion",
      }
    },
    "pricing": {
      "pricing_model": "CBP",
      "billable": false,
      "category": "referral_conversion"
    }
   }]
}

Stato: messaggio consegnato

Il seguente webhook viene ricevuto quando un messaggio inviato da un'azienda come parte di una conversazione avviata dall'utente viene consegnato (se la conversazione non è iniziata in un punto di accesso gratuito):

{
  "statuses": [{
    "id": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "delivered",
    "timestamp": "TIMESTAMP",
    "type": "message",
    "message": {
        "recipient_id":"WHATSAPP_ID" 
      },
    "conversation": {
      "id": "CONVERSATION_ID",
      "origin": {
         "type": "user_initiated"
      }
    },
    "pricing": {
      "pricing_model": "CBP",
      "billable": true,
      "category": "user_initiated"
    }
  }]
}

Il seguente webhook viene ricevuto quando un messaggio inviato da un'azienda come parte di una conversazione avviata dall'azienda viene consegnato:

{
  "statuses": [{
    "id": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "delivered",
    "timestamp": "TIMESTAMP",
    "type": "message",
    "message": {
        "recipient_id": "WHATSAPP_ID" 
    },
    "conversation": {
      "id": "CONVERSATION_ID",
      "origin": {
         "type": "business_initiated"
      }
    },
    "pricing": {
      "pricing_model": "CBP",
      "billable": true,
      "category": "business_initiated"
    }
  }]
}

Il seguente webhook viene ricevuto quando un messaggio inviato da un'azienda come parte di una conversazione avviata dall'utente e originata da un punto di accesso gratuito viene consegnato:

{
  "statuses": [{
    "id": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "delivered",
    "timestamp": "TIMESTAMP",
    "type": "message",  
    "message": {
        "recipient_id": "WHATSAPP_ID" 
    },
    "conversation": {
      "id": "CONVERSATION_ID",
      "origin": {
         "type": "referral_conversion",
      }
    },
    "pricing": {
      "pricing_model": "CBP",
      "billable": false,
      "category": "referral_conversion"
    }
  }]
}

Stato: messaggio letto

Callback standard per un messaggio letto:

{
  "statuses":[{
    "id": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "read",
    "timestamp": "TIMESTAMP",
    "type": "message",  
    "message": {
        "recipient_id": "WHATSAPP_ID" 
    }
  }]
}

Stato: invio del messaggio non riuscito

Codice errore 470

{
  "statuses": [{
    "errors": [{
      "code": 470,
      "title": "Failed to send message because you are outside the support window for freeform messages to this user. Please use a valid HSM notification or reconsider." 
    }],
    "id": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "failed",
    "timestamp": "TIMESTAMP"
  }]
}

Codice errore 480

{
  "statuses": [{
      "errors": [{
          "code": 480,
          "title": "Failed to send message since we detect an identity change of the contact"
      }],
      "id": "ID",
      "recipient_id": "WHATSAPP_ID",
      "status": "failed",
      "timestamp": "TIMESTAMP"
   }]
}

La sottosezione conversation non è inclusa nella callback se un messaggio non è stato inviato. In questo caso, non è implicata alcuna attivazione di billing o conversation.

Stato: messaggio eliminato

Callback standard per un messaggio eliminato:

{
  "statuses": [{
        "id": "ID",
        "recipient_id": "WHATSAPP_ID",
        "status": "deleted",
        "timestamp": "TIMESTAMP",
        "type": "message",
        "message": {
           "recipient_id": "WHATSAPP_ID" 
      }
    }]
}

La sottosezione conversation non è inclusa nella callback se un messaggio è stato eliminato. In questo caso, non è prevista alcuna attivazione di billing o conversation.

Tutti i possibili stati dei messaggi

Per maggiori informazioni, consulta Panoramica, Messaggi.

FAQ

I’m getting a message read webhook alert including pricing information. Is that expected?

Yes, there is a specific scenario where you can get pricing information on your webhook alert for read messages. For each sent message, there can be 3 scenarios:

Scenario	When it Happens
You get a webhook alert when the message is delivered (including pricing information) and another webhook alert when the message is read (not including pricing information).	This is the most common scenario.
You get a webhook alert when the message is delivered (including pricing information). You do not get a webhook alert that the message has been read.	Common when a customer has turned off the feature that lets people know they have read a message.
You get a webhook alert when the message is read (including pricing information). You do not get a webhook alert that the message has been delivered.	Only triggered when the user is already reading the thread with the business when the message comes in.

Permalink