logoDocumentation
Rechercher

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 :
  • business_initiated : La conversation commence lorsque l'entreprise envoie le premier message au client. Cela s'applique à tout moment supérieur à 24 heures après le dernier message du client.
  • customer_initiated : La conversation commence avec la réponse de l'entreprise au message du client. Cela s'applique uniquement si la réponse de l'entreprise intervient dans les 24 heures suivant le dernier message du client.
  • referral_conversion : La conversation provient d'un point d'entrée gratuit. Ces conversations sont toujours initiées par les clients.
  • pricing
    Champ Type Option Description
    pricing_model String optionnel valeur fixe : CBP
    category String optionnel catégorie tarifaire du dialogue. Valeurs valides :
  • business_initiated : Conversation commerçant.
  • customer_initiated : Conversation utilisateur.
  • referral_conversion : Conversation point d'accès gratuit.
  • 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" } } } ] }
                  
                  {
        "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"
                    }
                }
            }
        ]
    }
    
                
    Afficher ce bloc de code dans la fenêtre flottante

    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" } } } } } ] }
                  
                  {
        "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"
                            }
                        }
                    }
                }
            }
        ]
    }
    
                
    Afficher ce bloc de code dans la fenêtre flottante

    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 } } }] }
                  
                  {"total":1, 
      "rows":[{
      "server": "whatsapp", 
      "itime":1640707579,
      "notification":{
          "event":"insufficient_balance",
        "notification_data":{
          "whatsapp_business_account_id":"",
          "remain_balance": 5.1234,					
          "balance_threshold": 10
        }
      }
    }]
    }
    
                
    Afficher ce bloc de code dans la fenêtre flottante
    icon
    Contactez-nous