API de rappel
Vue d'ensemble
Les données de "statut du message" et de "réponse au message" sont rappelées vers le système métier de l'entreprise, et ces informations peuvent être utilisées pour effectuer des actions telles que des statistiques et des réponses aux utilisateurs.
Adresse de rappel
Les entreprises doivent configurer des adresses de rappel pour recevoir le statut des messages et les réponses aux messages. Pour plus d'informations, consultez paramètres de rappel.
Format de rappel
La méthode de requête est POST, le corps de la requête est en JSON, et le type de données est "Content-Type: application/json".
Plusieurs enregistrements de données sont retournés à la fois.
Mécanisme de sécurité
À mettre en ligne. Actuellement, le rappel ne contient pas d'informations d'authentification, il ne faut donc pas définir de vérification d'autorisation pour l'API qui reçoit le rappel côté développeur.
Mécanisme de réponse
Après avoir reçu le rappel EngageLab, le service développeur doit répondre dans les 3 secondes comme suit :
reçu avec succès : le code de statut HTTP doit retourner 200 et aucun message de réponse n'est requis.
Mécanisme de réessai
À mettre en ligne.
Paramètres de la requête
Les paramètres de requête EngageLab vers l'adresse de rappel du système métier sont les suivants :
| Champ | Type | Option | Description |
|---|---|---|---|
| total | int | requis | volume de données rappelées |
| rows | Tableau JSON | requis | détails du rappel |
Les paramètres dans rows sont les suivants :
| Champ | Type | Option | Description |
|---|---|---|---|
| message_id | string | optionnel | le statut du message et la réponse. |
| from | string | optionnel | L'expéditeur, le statut du message, et retourné lors de l'envoi du message en amont. |
| to | string | optionnel | Le destinataire, le statut du message, et le message en amont. |
| server | string | requis | Le service produit auquel appartient l'information de rappel. La valeur fixe est whatsapp. |
| channel | string | optionnel | Le canal auquel appartient le statut ou la réponse. La valeur fixe est whatsapp |
| itime | int | requis | l'horodatage généré par les données de rappel. Vous pouvez utiliser le champ message_status pour obtenir l'horodatage de la requête, de l'envoi, de la livraison et de la lecture. |
| custom_args | Objet JSON | optionnel | Champs optionnels personnalisés lors de l'envoi du message, retournés tels quels dans le rappel de statut du message. |
| status | Objet JSON | optionnel | Champ de statut du message |
| response | Objet JSON | optionnel | Champs de réponse au message |
Statut du message - status
Paramètres de rappel
| Champ | Type | Option | Description |
|---|---|---|---|
| message_status | string | requis | le statut du message. |
| status_data | Objet JSON | optionnel | données détaillées dans cet état |
| error_code | int | optionnel | le code d'erreur. En cas d'échec, le code d'erreur est retourné. |
| error_detail | Objet JSON | optionnel | les détails de l'erreur. Le message d'erreur est retourné en cas d'échec. |
| loss | Objet JSON | optionnel | étape de perte et source de perte |
message_status - response
| Valeur | Description | Définition |
|---|---|---|
| plan | envoi planifié | le numéro est dans le "numéro du destinataire" pour enregistrer le statut d'une cible d'envoi planifié. |
| target_valid | cible valide | Validation réussie 1. Le numéro est jugé valide par EngageLab. 2. Le numéro est jugé valide par le service Meta WhatsApp. |
| sent | envoyé avec succès | Le message d'erreur retourné après que EngageLab a soumis le numéro au service Meta WhatsApp. |
| delivered | livré avec succès | Le service Meta WhatsApp confirme que le message a été livré à l'utilisateur. |
| read | lu | Le service Meta WhatsApp confirme que l'utilisateur a lu le message. |
| target_invalid | la cible est invalide. | 1. Le numéro est jugé invalide par EngageLab. 2. Le numéro est jugé invalide par le service Meta WhatsApp. |
| sent_failed | Échec de l'envoi | Le message d'erreur retourné après la soumission du numéro au service Meta WhatsApp. |
| delivered_failed | échec de la livraison | Le numéro a été soumis au service Meta WhatsApp, mais le rappel Meta a échoué. |
| delivered_timeout | Non livré après expiration du délai | Le numéro a été soumis avec succès au service Meta WhatsApp, mais Meta n'a pas rappelé dans les 5 minutes pour indiquer si la livraison a réussi ou échoué, ce qui est compté comme un délai dépassé. |
status_data
| Champ | Type | Option | Description |
|---|---|---|---|
| msg_time | int | requis | l'heure à laquelle le message a été envoyé. |
| channel_message_id | String | requis | l'ID du message retourné par WhatsApp. |
| whatsapp_business_account_id | String | requis | l'ID du compte WhatsApp Business auquel appartient le numéro d'envoi. |
| timezone | String | requis | fuseau horaire de l'organisation |
| plan_user_total | int | optionnel | le nombre total de cibles planifiées. Cette valeur n'est disponible que lorsque message_status = plan. |
| country_code | String | requis | le code pays du numéro de téléphone du destinataire. |
| from_phone_id | String | requis | ID du numéro d'envoi (from) |
| conversation | Objet JSON | optionnel | Informations de session |
| pricing | Objet JSON | optionnel | Informations tarifaires |
conversation
| Champ | Type | Option | Description |
|---|---|---|---|
| id | String | optionnel | l'ID de la conversation Meta à laquelle appartient le message. |
| origin | Objet JSON | optionnel | Indique qui a initié la conversation. Spécifié par type. Exemple : "origin":{"type":"business_initiated"}. Valeurs valides : |
pricing
| Champ | Type | Option | Description |
|---|---|---|---|
| pricing_model | String | optionnel | valeur fixe : CBP |
| category | String | optionnel | catégorie tarifaire du dialogue. Valeurs valides : |
error_detail
| Champ | Type | Option | Description |
|---|---|---|---|
| message | String | requis | cause |
loss
| Champ | Type | Option | Description |
|---|---|---|---|
| loss_step | int | requis | étape de perte 1 : Cible planifiée vers cible effective, c'est-à-dire cible invalide 2 : Cible valide ~ envoi, c'est-à-dire échec d'envoi 3 : Envoi vers livraison. Livraison échouée |
| loss_source | String | requis | la source de la perte. Valeurs valides : engagelab : perte WhatsApp EngageLab causée par la vérification du service meta : l'erreur retournée par Meta. |
Exemple de rappel
{
"total": 1,
"rows": [
{
"message_id": "1666165485030094861", // id du message EngageLab
"from": "", // expéditeur
"to": "", // destinataire
"server": "whatsapp",
"channel": "whatsapp",
"itime": 1640707579, // Horodatage généré par le statut du message, par exemple l'heure de livraison du message
"custom_args": {}, // Les paramètres soumis lors de la création de ce message seront retournés tels quels lors de ce rappel
"status": {
// Répondre avec ces champs en cas de succès
"message_status": "delivered", // statut du message
"status_data": { // personnalisé
"msg_time": 1663432355, // Heure d'envoi du message, heure d'envoi dans l'historique, c'est-à-dire heure à laquelle l'utilisateur appelle l'API pour envoyer le message - l'appel à l'API est réussi
"channel_message_id": "wamid.123321abcdefed==", // optionnel, msgid retourné par Meta
"whatsapp_business_account_id": "", //Numéro d'envoi du compte WhatsApp Business correspondant
"timezone": "", //Fuseau horaire de l'organisation
"plan_user_total": 2007, //Nombre total de cibles planifiées, n'aura une valeur que lorsque message_status=plan
"country_code": "CN", //Code pays/région du numéro de téléphone du destinataire
"from_phone_id": "111111", // ID du numéro d'envoi (from)
"conversation": { // optionnel, informations de session
"id": "ebe2398cdaa37a0899ca5268b987b0c8",
"origin": {
"type": "business_initiated"
}
},
"pricing": { // optionnel, informations tarifaires
"pricing_model": "CBP",
"category": "business_initiated"
}
},
// Retourner ces champs en cas d'échec (destination invalide, échec d'envoi, échec de livraison, non lu)
"error_code": 0, //code d'erreur
"error_detail": {
"message": "" //raison de l'erreur
},
"loss": {
"loss_step": 1,
"loss_source": "aa"
}
}
}
]
}
Réponse au message
Paramètres de rappel
| Champ | Type | Option | Description |
|---|---|---|---|
| event | string | optionnel | événement de réponse |
| response_data | Objet JSON | optionnel | contenu du message de réponse/interaction en amont |
event
| Valeur | Description | Détails |
|---|---|---|
| received | messages reçus de l'utilisateur | l'utilisateur a envoyé un message directement. |
| reply | l'utilisateur a répondu à votre message. | L'entreprise envoie d'abord un message à l'utilisateur, puis l'utilisateur choisit d'y répondre. |
| order | commandes utilisateur | - |
| deleted | l'utilisateur a supprimé son message. | L'utilisateur a supprimé le message qu'il a lui-même envoyé (à venir) |
response_data
| Champ | Type | Option | Description |
|---|---|---|---|
| channel_message_id | String | requis | l'ID du message retourné par WhatsApp. |
| whatsapp_business_account_id | String | requis | l'ID du compte WhatsApp Business auquel appartient le numéro d'envoi. |
| contact | Objet JSON | optionnel | informations sur l'expéditeur |
| message | Objet JSON | requis | contenu du message |
| message_context | Objet JSON | Optionnel | Contexte du message, apparaît lors de l'événement de réponse, indique à quel message l'utilisateur a répondu |
contact
| Champ | Type | Option | Description |
|---|---|---|---|
| profile | Objet JSON | optionnel | informations de l'expéditeur (client). Actuellement, seul le champ name indique le nom du client. Exemple : "profile": {"name": "bob"} |
| wa_id | String | optionnel | numéro de l'expéditeur. |
message
| Champ | Type | Option | Description |
|---|---|---|---|
| type | String | requis | valeurs valides : text, image, audio, video, document, sticker, button, interactive, unknown, et order. |
| text | Objet JSON | optionnel | Pour plus d'informations, voir description de l'objet text |
| image | Objet JSON | optionnel | pour plus d'informations, voir description de l'objet image |
| audio | Objet JSON | optionnel | pour plus d'informations, voir description de l'objet audio |
| video | Objet JSON | optionnel | pour plus d'informations, voir description de l'objet video |
| document | Objet JSON | optionnel | pour plus d'informations, voir description de l'objet document |
| sticker | Objet JSON | optionnel | pour plus d'informations, voir description de l'objet sticker |
message_context
| Champ | Type | Option | Description |
|---|---|---|---|
| origin_from_phone | String | Requis | Le numéro d'envoi du message référencé, à noter qu'il n'y a ni espaces ni symboles + ici |
| origin_channel_message_id | String | Requis | L'id unique du message référencé |
| origin_from_phone_id | String | Optionnel | L'id du numéro d'envoi du message référencé, ce champ est normalement présent |
| origin_message_id | String | Optionnel | L'id du message référencé, ce champ est normalement présent |
Exemple de rappel
{
"total": 1,
"rows": [
{
"message_id": "1666165485030094861", // id du message côté Jiguang
"from": "", // expéditeur, c'est-à-dire le numéro de mobile du client
"to": "", // destinataire, c'est-à-dire le numéro d'envoi du développeur
"server": "whatsapp",
"channel": "whatsapp",
"itime": 1640707579, // horodatage
"response": {
"event": "", // événement de réponse
"response_data": { // contenu spécifique du message
"channel_message_id": "wamid.123321abcdefed==", // optionnel, msgid retourné par Meta
"whatsapp_business_account_id": "123321", //Numéro d'envoi du développeur vers le compte WhatsApp Business correspondant
"contact": { // optionnel, informations sur l'expéditeur
"profile": {
"name": "bob" // surnom de l'expéditeur
},
"wa_id": "8613800138000" // numéro de l'expéditeur
},
"message": { // contenu spécifique du message
"type": "text", // Type du message, permet d'identifier le champ spécifique selon cette valeur, par exemple text, le contenu est le champ text
"text": { // contenu du message
"body": "ici le texte du contenu du message"
}
}
}
}
}
]
}
Notification de message - Notification
Paramètres de rappel
| Champ | Type | Option | Description |
|---|---|---|---|
| event | string | Optionnel | Événement de réponse |
| notification_data | Objet JSON | Optionnel | Contenu spécifique de la notification de message système |
event
| Valeur | Description | Explication détaillée |
|---|---|---|
| insufficient_balance | Solde insuffisant | Le solde en temps réel est inférieur au seuil que vous avez défini (par défaut 10 $) |
| template_update | Statut du modèle modifié | Changement de statut du modèle et changement de qualité du modèle |
| phone_number_update | Statut du numéro d'envoi modifié | Changement de statut du numéro d'envoi, actuellement seuls les changements de "limite d'envoi de message" sont pris en charge officiellement, les valeurs incluent : TIER_50:50 clients/24 heures TIER_250:250 clients/24 heures TIER_1K:1000 clients/24 heures TIER_10K:10000 clients/24 heures TIER_100K:100000 clients/24 heures TIER_UNLIMITED:Illimité |
| whatsapp_business_update | Compte WABA modifié | Compte WABA banni, averti, etc. |
notification_data
| Champ | Type | Option | Description |
|---|---|---|---|
| whatsapp_business_account_id | String | Requis | Numéro de compte WhatsApp Business |
| remain_balance | int | Optionnel | Présent lorsque l'événement est insufficient_balance Valeur du solde en temps réel (USD) |
| balance_threshold | int | Optionnel | Présent lorsque l'événement est insufficient_balance Seuil d'alerte de solde défini (USD) |
| template_id | String | Optionnel | Présent lorsque l'événement est template_update ID du modèle |
| template_name | String | Optionnel | Présent lorsque l'événement est template_update Nom du modèle |
| template_language | String | Optionnel | Présent lorsque l'événement est template_update Langue du modèle |
| template_status | String | Optionnel | Présent lorsque l'événement est template_update Statut du modèle, valeurs : APPROVED/REJECTED/PENDING/DISABLED/FLAGGED/REINSTATED |
| template_status_reason | String | Optionnel | Présent lorsque l'événement est template_update Raison du changement, généralement utilisée lors du rejet de la validation du modèle, sinon la chaîne "NONE" ou n'existe pas |
| phone_number_id | String | Optionnel | Présent lorsque l'événement est phone_number_update ID du numéro d'envoi |
| display_phone_number | String | Optionnel | Présent lorsque l'événement est phone_number_update, numéro de téléphone d'envoi, exemples : +1 320-302-7083 +86 183 7981 2430 |
| current_limit | String | Optionnel | Présent lorsque l'événement est phone_number_update Limite actuelle du numéro d'envoi, valeurs : TIER_50/TIER_250/TIER_1K/TIER_10K/TIER_100K/TIER_UNLIMITED |
| waba_event | String | Optionnel | Présent lorsque l'événement est whatsapp_business_update, valeurs actuelles : DISABLED_UPDATE Compte désactivé ACCOUNT_VIOLATION Violation du compte |
| ban_state | String | Optionnel | Présent lorsque l'événement est whatsapp_business_update et waba_event est DISABLED_UPDATE, valeur actuelle : DISABLE Désactivé |
| violation_type | String | Optionnel | Présent lorsque l'événement est whatsapp_business_update et waba_event est ACCOUNT_VIOLATION, valeurs actuelles : SPAM Signalé comme spam/harcèlement SCAM Signalé comme fraude |
Exemple de rappel
{"total":1,
"rows":[{
"server": "whatsapp",
"itime":1640707579,
"notification":{
"event":"insufficient_balance",
"notification_data":{
"whatsapp_business_account_id":"",
"remain_balance": 5.1234,
"balance_threshold": 10
}
}
}]
}

