Notifications de statuts et tarifs

Le client de l’API WhatsApp Business envoie des notifications concernant le statut (status) du message entre les utilisateur·trices et vous-même. Ces notifications sont transmises via l’objet statuses.

Mise à jour des statuts

Pour chaque message que votre entreprise envoie, vous recevez une notification de statut. Pour connaître l’équivalent dans l’application WhatsApp de chaque statut (si un tel équivalent existe), rendez-vous dans le tableau ci-dessous et cliquez sur la flèche dans la colonne de gauche.

Nom	Description
`deleted`	L’utilisateur·ice a envoyé un message et l’a supprimé ensuite. À réception de cette notification, vous devez vous assurer que le message est bien supprimé de votre système s’il a été téléchargé depuis le serveur.
Équivalent dans l’application WhatsApp	Le message est remplacé dans WhatsApp par une note de type « Ce message a été supprimé ».
`delivered`	Un message envoyé par votre entreprise a été distribué sur l’appareil de l’utilisateur·ice.
Équivalent dans l’application WhatsApp	Deux coches
`failed`	Un message envoyé par votre entreprise n’a pas été distribué. Le motif de cet échec figurera dans le rappel. Vérifiez la documentation du message d’erreur pour faciliter le débogage : Erreurs de l’API On-Premises Codes d’erreur de l’API Cloud et dépannage
Équivalent dans l’application WhatsApp	Triangle rouge représentant une erreur
`read`	Un message envoyé par votre entreprise a été lu par l’utilisateur·ice. Les notifications `read` ne sont disponibles que pour les utilisateur·ices dont l’accusé de lecture est activé. Les utilisateur·ices dont l’accusé de lecture n’est pas activé reçoivent uniquement la notification `delivered` .
Équivalent dans l’application WhatsApp	Deux coches bleues
`sent`	Un message envoyé à votre entreprise est en cours de réception dans nos systèmes. Pour les utilisateurs de l'API On-Premises : pour recevoir des notifications pour les messages au statut `sent` , définissez le paramètre `sent_status` sur `true` dans les paramètres de l’application. La notification de statut `sent` est désactivée par défaut.
Équivalent dans l’application WhatsApp	Une coche
`warning`	Un message envoyé par votre entreprise contient un article d’un catalogue qui n’est pas disponible ou qui n’existe pas.

L’ordre de ces notifications dans votre application peut ne pas correspondre au statut du message en temps réel. Il est parfois nécessaire de s’en assurer en vérifiant l’horodatage.

Pour qu’un statut soit lu (statut read), il doit avoir été distribué (statut delivered). Dans certains cas, par exemple lorsqu’un utilisateur ou une utilisatrice se sert de l’écran de discussion instantanée et qu’un message arrive, ce dernier présente les statuts delivered et read presque simultanément. Dans ce cas ou pour d’autres scénarios similaires, la notification delivered ne sera pas renvoyée, car la lecture d’un message implique nécessairement que celui-ci a été distribué. Ce comportement est appliqué à des fins d’optimisation interne.

Mise à jour des tarifs

Depuis le 1er février 2022, l’objetstatuses de vos notifications sortantes inclut deux objets imbriqués : conversation et pricing. Les composants d’objet de conversation et de tarification peuvent varier en fonction de l’origine de la conversation. Les conversations peuvent être lancées par l’utilisateur·trice, par l’entreprise ou commencées à partir d’un point d’entrée gratuit. Vous trouverez plus d’informations ci-dessous :

Exemples

Dans les exemples suivants, le champ recipient_id peut être remplacé par un champ group_id. Cela dépend si le message est envoyé à un individu ou à un groupe.

Statut “message envoyé”

Vous recevez le webhook ci-dessous lorsqu’une entreprise envoie un message dans le cadre d’une conversation lancée par l’utilisateur·trice (si cette conversation n’a pas démarré dans un point d’entrée gratuit) :

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

Vous recevez le webhook ci-dessous lorsqu’une entreprise envoie un message dans le cadre d’une conversation lancée par l’utilisateur·trice pour un message multimédia (si cette conversation n’a pas démarré dans un point d’entrée gratuit) :

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

Vous recevez le webhook ci-dessous lorsqu’une entreprise envoie un message dans le cadre d’une conversation lancée par l’entreprise :

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

Vous recevez le webhook ci-dessous lorsqu’une entreprise envoie un message en réponse à une conversation lancée par l’utilisateur·trice depuis un point d’entrée gratuit :

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

Statut “Message distribué”

Vous recevez le webhook ci-dessous lorsqu’un message d’entreprise est distribué et fait partie d’une conversation lancée par l’utilisateur·trice (si cette conversation n’a pas démarré dans un point d’entrée gratuit) :

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

Vous recevez le webhook ci-dessous lorsqu’un message d’entreprise est distribué et fait partie d’une conversation lancée par l’entreprise :

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

Vous recevez le webhook ci-dessous lorsqu’un message d’entreprise est distribué et fait partie d’une conversation lancée par l’utilisateur·trice depuis un point d’entrée gratuit :

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

Statut “Message lu”

Rappel standard pour un message lu :

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

Statut “Message non envoyé”

Code d’erreur 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"
  }]
}

Code d’erreur 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 sous-section conversation n’est pas incluse dans le rappel si un message n’a pas été envoyé. Dans ce cas, aucune activation de facturation ou de conversation n’est appliquée.

Statut “Message supprimé”

Rappel standard pour un message supprimé :

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

La sous-section conversation n’est pas incluse dans le rappel si un message a été supprimé. Dans ce cas, aucune activation de facturation ou de conversation n’est appliquée.

Tous les statuts de message possibles

Pour en savoir plus, voir la page Vue d’ensemble des messages.

Questions/réponses

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.

Permalien