Logo Site EngageLab Mark Colored TransparentDocumentation
SMS
Accueil de la Documentation
DocumentationRéférence API
Rechercher
Connexion
Référence API/Référence des événements de callback
Référence APIRéférence des événements de callback...

Référence des événements de callback

Dernière Mise à jour：5 days ago

Configuration et vérification de l'URL de callback

Une fois l'URL de callback configurée, EngageLab SMS envoie automatiquement une requête HTTP POST à cette adresse afin de vérifier la disponibilité de l'interface. Votre service doit retourner un code de statut HTTP 200 dans un délai de 3 secondes, faute de quoi le système considérera l'adresse comme indisponible.

Remarque :
Pour garantir la bonne réception des données de callback, veuillez ajouter 119.8.170.74 et 114.119.180.30 à la liste blanche du pare-feu de votre serveur.

Exemple de requête

En supposant que votre URL de callback soit https://example.engagelabSMS.callback.com, le système enverra la requête suivante :

curl -X POST https://example.engagelabSMS.callback.com -d '{}'
              
              curl -X POST https://example.engagelabSMS.callback.com -d '{}'
Afficher ce bloc de code dans la fenêtre flottante

Exigences relatives à la réponse

Votre service doit uniquement retourner un code de statut HTTP 200, sans aucun contenu. Par exemple :

HTTP/1.1 200 OK Content-Length: 0
              
              HTTP/1.1 200 OK
Content-Length: 0
Afficher ce bloc de code dans la fenêtre flottante

Remarque :
La vérification de l'URL de callback ne contrôle que le code de statut HTTP et n'exige pas le renvoi d'un contenu spécifique. Assurez-vous que l'interface de votre service peut répondre correctement avec un code 200 dans un délai de 3 secondes.

Mécanismes de sécurité du callback

Afin de garantir la sécurité des données de callback et la fiabilité de leur source, EngageLab SMS prend en charge plusieurs méthodes de vérification de sécurité.

Vérification par nom d'utilisateur et clé secrète (facultatif)

  • Configuration facultative. Si un nom d'utilisateur est défini, une clé secrète doit également l'être.
  • Une fois configuré, EngageLab ajoute le champ X-CALLBACK-ID à l'en-tête HTTP de chaque requête de callback, selon le format suivant :
X-CALLBACK-ID: timestamp={timestamp};nonce={nonce};username={username};signature={signature}
              
              X-CALLBACK-ID: timestamp={timestamp};nonce={nonce};username={username};signature={signature}
Afficher ce bloc de code dans la fenêtre flottante
  • Où :
    • timestamp : horodatage de l'envoi du callback
    • nonce : nombre aléatoire
    • username : le nom d'utilisateur que vous avez configuré
    • signature : information de signature, calculée comme suit

Méthode de calcul de la signature (exemple en Python)

import hashlib, hmac def verify(username, secret, timestamp, nonce, signature): return signature == hmac.new( key=secret.encode(), msg=f'{timestamp}{nonce}{username}'.encode(), digestmod=hashlib.sha256 ).hexdigest()
              
              import hashlib, hmac
def verify(username, secret, timestamp, nonce, signature):
    return signature == hmac.new(
        key=secret.encode(),
        msg=f'{timestamp}{nonce}{username}'.encode(),
        digestmod=hashlib.sha256
    ).hexdigest()
Afficher ce bloc de code dans la fenêtre flottante
  • Le serveur peut vérifier la légitimité de la requête de callback à l'aide de la méthode ci-dessus.

Authentification Authorization (facultatif)

  • Si votre interface de callback nécessite une authentification (telle que Basic Auth, Bearer Token, etc.), vous pouvez renseigner les informations d'Authorization lors de la configuration.
  • EngageLab inclura automatiquement ce champ Authorization lors de la requête, ce qui permet à votre service de vérifier l'identité de la requête.

Description des événements de callback

Statut des messages

Le statut des messages permet de suivre les changements d'état de chaque message tout au long de son cycle de vie. Il offre une visibilité en temps réel sur la progression de l'envoi, de la livraison, de la vérification, etc., facilitant l'analyse statistique, le traitement des anomalies et l'optimisation de l'expérience utilisateur.

Identifiant de l'événement Description
plan Message planifié pour l'envoi, ajouté à la file d'attente
target_valid Numéro de destination valide
target_invalid Numéro de destination invalide
sent Message envoyé avec succès
sent_failed Échec de l'envoi du message
delivered Message livré sur l'appareil de l'utilisateur
delivered_failed Message envoyé, mais non livré sur l'appareil de l'utilisateur

Structure des données de callback

Structure externe

{ "total": 1, "rows": [ { // Objet ReportLifecycle } ] }
              
              {
  "total": 1,
  "rows": [
    {
      // Objet ReportLifecycle
    }
  ]
}
Afficher ce bloc de code dans la fenêtre flottante
Nom du champ Type Description
total int Nombre d'éléments de données contenus dans ce callback
rows array Tableau des données de statut du cycle de vie

Objet ReportLifecycle

Nom du champ Type Description
message_id string ID unique du message
to string Numéro du destinataire
server string Type de service (par ex. SMS)
channel string Type de canal
itime int64 Horodatage du callback (secondes)
custom_args object Paramètres personnalisés (renvoyés s'ils ont été transmis)
status object Objet détaillant le statut

Objet status

Nom du champ Type Description
message_status string Statut actuel du message (voir le tableau ci-dessous)
status_data object Objet de données de statut
billing object Objet d'informations de facturation (renvoyé en cas de facturation)
error_code int Code d'erreur, 0 indiquant l'absence d'erreur
error_detail object Détail de l'erreur (renvoyé en cas d'erreur)

Objet status_data

Nom du champ Type Description
msg_time int64 Horodatage de création du message (secondes)
message_id string ID du message
current_send_channel string Nom du canal d'envoi actuel
template_key string Clé de configuration du modèle
business_id string ID de l'activité
plan_id string ID du plan

Objet billing (renvoyé en cas de facturation)

Nom du champ Type Description
cost float64 Montant des frais
currency string Devise, fixée à « USD »

En règle générale, seuls les messages à l'étape « sent » contiennent des informations de facturation.

Objet error_detail (renvoyé en cas d'erreur)

Nom du champ Type Description
message string Description du message d'erreur

Exemple : message envoyé avec succès

{ "total": 1, "rows": [ { "message_id": "123456789", "to": "+6598765432", "server": "sms", "channel": "sms", "itime": 1701234567, "custom_args": { "order_id": "ORDER123", "user_id": "USER456" }, "status": { "message_status": "sent", "status_data": { "msg_time": 1701234560, "message_id": "123456789", "current_send_channel": "CHANNEL_A", "template_key": "verify_code", "business_id": "1001", "plan_id": "7198765432109876543" }, "billing": { "cost": 0.005, "currency": "USD" }, "error_code": 0 } } ] }
              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456789",
      "to": "+6598765432",
      "server": "sms",
      "channel": "sms",
      "itime": 1701234567,
      "custom_args": {
        "order_id": "ORDER123",
        "user_id": "USER456"
      },
      "status": {
        "message_status": "sent",
        "status_data": {
          "msg_time": 1701234560,
          "message_id": "123456789",
          "current_send_channel": "CHANNEL_A",
          "template_key": "verify_code",
          "business_id": "1001",
          "plan_id": "7198765432109876543"
        },
        "billing": {
          "cost": 0.005,
          "currency": "USD"
        },
        "error_code": 0
      }
    }
  ]
}
Afficher ce bloc de code dans la fenêtre flottante

Exemple : échec de l'envoi du message

{ "total": 1, "rows": [ { "message_id": "123456790", "to": "+6598765433", "server": "sms", "channel": "sms", "itime": 1701234568, "status": { "message_status": "sent_fail", "status_data": { "msg_time": 1701234561, "message_id": "123456790", "current_send_channel": "CHANNEL_B", "template_key": "verify_code", "business_id": "1001", "plan_id": "7198765432109876543" }, "error_code": 4001, "error_detail": { "message": "Invalid phone number" } } } ] }
              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456790",
      "to": "+6598765433",
      "server": "sms",
      "channel": "sms",
      "itime": 1701234568,
      "status": {
        "message_status": "sent_fail",
        "status_data": {
          "msg_time": 1701234561,
          "message_id": "123456790",
          "current_send_channel": "CHANNEL_B",
          "template_key": "verify_code",
          "business_id": "1001",
          "plan_id": "7198765432109876543"
        },
        "error_code": 4001,
        "error_detail": {
          "message": "Invalid phone number"
        }
      }
    }
  ]
}
Afficher ce bloc de code dans la fenêtre flottante

Notifications de messages

Les notifications de messages désignent des événements métier ou des alertes de niveau système. Elles servent à attirer l'attention de l'équipe métier sur l'état de fonctionnement du service, le solde, la validation des modèles et d'autres informations importantes, facilitant ainsi le traitement en temps voulu et la prévention des risques.

Identifiant de l'événement Description
template_audit_result Notification du résultat de validation d'un modèle

Réponses de messages

Les réponses de messages désignent principalement les événements de réponse de callback lors des interactions avec les utilisateurs ou des systèmes externes.

Identifiant de l'événement Description
uplink_message Contenu des messages entrants envoyés par les utilisateurs, notamment par SMS

Exemple

{ "total": 1, "rows": [ { "server": "SMS", "itime": 1741083306, "message_id": "0", "business_id": "0", "response": { "event": "uplink_message", "response_data": { "message_sid": "SM1234567890", "account_sid": "AC1234567890", "from": "+1234567890", "to": "+0987654321", "body": "Hello, it's time to struggle!" } } } ] }
              
              {
    "total": 1,
    "rows": [
        {
            "server": "SMS",
            "itime": 1741083306,
            "message_id": "0",
            "business_id": "0",
            "response": {
                "event": "uplink_message",
                "response_data": {
                    "message_sid": "SM1234567890",
                    "account_sid": "AC1234567890",
                    "from": "+1234567890",
                    "to": "+0987654321",
                    "body": "Hello, it's time to struggle!"
                }
            }
        }
    ]
}
Afficher ce bloc de code dans la fenêtre flottante

Événements système

Les événements système couvrent les actions liées aux comptes, aux modèles, aux appels d'API, etc. Ils facilitent la surveillance, l'audit et le traitement automatisé d'opérations clés telles que les connexions aux comptes, les modifications de clés et les appels d'API.

Identifiant de l'événement Description
account_login Notification des opérations liées à la connexion au compte
key_manage Notification des opérations de modification, de gestion, etc. des clés
template_manage Notification des opérations d'ajout, de modification, de suppression, etc. de modèles
api_call Notification des opérations liées aux appels d'API

Structure des données de callback

Structure externe

{ "total": 1, "rows": [ { // Objet d'événement système } ] }
              
              {
  "total": 1,
  "rows": [
    {
      // Objet d'événement système
    }
  ]
}
Afficher ce bloc de code dans la fenêtre flottante
Champ Type Description
total int64 Nombre total d'événements contenus dans ce callback
rows array Tableau des objets d'événements système

Objet d'événement système

Champ Type Description
server string Fixé à « SMS »
itime int64 Horodatage de survenance de l'événement (secondes)
system_event object Contenu de l'événement système

Objet system_event

Champ Type Description
event string Type d'événement
data object Données de l'événement

Objet data

Champ Type Description
business_id string ID de l'activité
org_id string ID de l'organisation
operator object Informations sur l'opérateur

Objet operator

Champ Type Description
email string E-mail de l'opérateur (le cas échéant)
api_key string API Key (le cas échéant)
ip_address string IP de l'opération

Structure de la requête

{ "total": 1, "rows": [ { "server": "SMS", "itime": 1694012345, "system_event": { "event": "account_login", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "api_key": "api-xxxx", "ip_address": "1.2.3.4" }, "account_login": { "action": "login_success" } } } } ] }
              
              {
  "total": 1,
  "rows": [
    {
      "server": "SMS",
      "itime": 1694012345,
      "system_event": {
        "event": "account_login",
        "data": {
          "business_id": "123",
          "org_id": "org-abc",
          "operator": {
            "email": "foo@example.com",
            "api_key": "api-xxxx",
            "ip_address": "1.2.3.4"
          },
          "account_login": {
            "action": "login_success"
          }
        }
      }
    }
  ]
}
Afficher ce bloc de code dans la fenêtre flottante

Événement de connexion au compte

Champ Type Description
action string Connexion réussie/Échec de connexion/Déconnexion
fail_reason string Motif de l'échec de connexion, renvoyé uniquement lorsque login_failed

Exemple

{ "event": "account_login", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "ip_address": "1.2.3.4" }, "account_login": { "action": "login_success" } } }
              
              {
  "event": "account_login",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "email": "foo@example.com",
      "ip_address": "1.2.3.4"
    },
    "account_login": {
      "action": "login_success"
    }
  }
}
Afficher ce bloc de code dans la fenêtre flottante

Événement de gestion des modèles

Champ Type Description
action string Créer un modèle/Mettre à jour un modèle/Supprimer un modèle
template_id string ID du modèle
template_name string Nom du modèle

Exemple

{ "event": "template_manage", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "ip_address": "1.2.3.4" }, "template_manage": { "action": "update template", "template_id": "tmpl-456", "template_name": "Verification Code" } } }
              
              {
  "event": "template_manage",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "email": "foo@example.com",
      "ip_address": "1.2.3.4"
    },
    "template_manage": {
      "action": "update template",
      "template_id": "tmpl-456",
      "template_name": "Verification Code"
    }
  }
}
Afficher ce bloc de code dans la fenêtre flottante

Événement de gestion des clés

Champ Type Description
action string Créer une clé/Mettre à jour une clé/Supprimer une clé/Consulter une clé
api_key string API Key
description string Description (facultatif)

Exemple

{ "event": "key_manage", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "ip_address": "1.2.3.4" }, "key_manage": { "action": "create", "api_key": "apikey-789", "description": "Créer une clé" } } }
              
              {
  "event": "key_manage",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "email": "foo@example.com",
      "ip_address": "1.2.3.4"
    },
    "key_manage": {
      "action": "create",
      "api_key": "apikey-789",
      "description": "Créer une clé"
    }
  }
}
Afficher ce bloc de code dans la fenêtre flottante

Événement d'appel d'API

Champ Type Description
api_path string Chemin de l'interface
method string Méthode HTTP

Exemple

{ "event": "api_call", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "api_key": "apikey-789", "ip_address": "1.2.3.4" }, "api_call": { "api_path": "/api/v1/messages/send", "method": "POST" } } }
              
              {
  "event": "api_call",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "api_key": "apikey-789",
      "ip_address": "1.2.3.4"
    },
    "api_call": {
      "api_path": "/api/v1/messages/send",
      "method": "POST"
    }
  }
}
Afficher ce bloc de code dans la fenêtre flottante
Icon Solid Transparent White Qiyu
Contactez-nous