Interface de callback de statut du cycle de vie

Ce document décrit la structure de données et la description des champs de l'interface de callback de statut du cycle de vie des messages. Lorsque le statut d'un message change, le système renvoie les informations de statut vers l'URL configurée par le client via une requête HTTP POST.

Méthode de callback

• Méthode de requête : POST
• Content-Type : application/json
• Réponse de succès : code de statut HTTP 200 ou 204
• Nouvelle tentative en cas d'échec : si le client ne renvoie pas de code de statut de succès, le système effectue automatiquement de nouvelles tentatives

Structure de données

1. Structure externe (ReportLifecycles)

              
              {
  "total": 1,
  "rows": [
    {
      // Tableau d'objets ReportLifecycle
    }
  ]
}

            

2. Objet ReportLifecycle

La structure de chaque élément du tableau rows est la suivante :

3. Objet Status

Objet de détails du statut :

Remarque : les champs suivants sont utilisés pour les statistiques internes et ne sont pas renvoyés au client via callback :

• analysis - Champ d'analyse statistique interne

4. Objet StatusData

Données de base liées au statut :

Remarque : les champs suivants sont des informations sensibles ou des champs internes, ils ont été filtrés et ne sont pas renvoyés au client via callback :

• message_content - Contenu du message (information sensible)
• parts - Nombre de fragments du message (champ interne)
• msg_type - Type de message (champ interne)
• protocol_type - Type de protocole (champ interne)
• supplier_ids - ID du fournisseur (information sensible)

5. Objet Billing

Informations de facturation (renvoyées uniquement lorsqu'il existe des données de facturation) :

Remarque : les champs suivants sont des champs de facturation internes et ne sont pas renvoyés au client via callback :

• cost10000 - Champ de facturation interne (unité au 1/10000)
• sender_cost10000 - Coût de l'expéditeur (unité au 1/10000)

6. Objet ErrorDetail

Détails d'erreur (renvoyés uniquement lorsqu'une erreur se produit) :

7. Objet KwaiExtra

Informations d'extension spécifiques aux clients Kwai (renvoyées uniquement en statut livré et pour les clients Kwai) :

Description des statuts de message

Valeurs de statut de message courantes :

Exemples de callback

Exemple 1 : message livré 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": "delivered",
        "status_data": {
          "msg_time": 1701234560,
          "message_id": "123456789",
          "current_send_channel": "CHANNEL_A",
          "template_key": "verify_code",
          "business_id": "1001"
        },
        "billing": {
          "cost": 0.005,
          "currency": "USD"
        },
        "error_code": 0
      }
    }
  ]
}

            

Exemple 2 : é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"
        },
        "error_code": 4001,
        "error_detail": {
          "message": "Invalid phone number",
          "channel_code": "INVALID_NUMBER",
          "channel_message": "The phone number format is invalid"
        }
      }
    }
  ]
}

            

Exemple 3 : échec de la livraison du message (avec informations de facturation)

              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456791",
      "to": "+6598765434",
      "server": "sms",
      "channel": "sms",
      "itime": 1701234570,
      "custom_args": {
        "campaign": "new_year_promo"
      },
      "status": {
        "message_status": "delivered_fail",
        "status_data": {
          "msg_time": 1701234562,
          "message_id": "123456791",
          "current_send_channel": "CHANNEL_C",
          "template_key": "marketing",
          "business_id": "1001"
        },
        "billing": {
          "cost": 0.0045,
          "currency": "USD"
        },
        "error_code": 5002,
        "error_detail": {
          "message": "Phone number unreachable",
          "channel_code": "UNREACHABLE",
          "channel_message": "Subscriber absent"
        }
      }
    }
  ]
}

            

Exemple 4 : message vocal livré pour un client Kwai

              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456792",
      "to": "+6598765435",
      "server": "voice",
      "channel": "voice",
      "itime": 1701234575,
      "status": {
        "message_status": "delivered",
        "status_data": {
          "msg_time": 1701234565,
          "message_id": "123456792",
          "current_send_channel": "VOICE_CHANNEL_A",
          "template_key": "voice_verify",
          "business_id": "2001"
        },
        "billing": {
          "cost": 0.012,
          "currency": "USD"
        },
        "error_code": 0,
        "kwai_extra": {
          "delivered_time": 1701234575000,
          "parts": 1,
          "duration": 45
        }
      }
    }
  ]
}

            

Points d'attention

1. Règles de retour des champs

   • Tous les champs marqués omitempty n'apparaissent pas dans le JSON retourné lorsque leur valeur est vide ou nulle
   • Les informations sensibles et les champs internes ont été filtrés ou effacés avant le callback

2. Sécurité

   • Le contenu du message (message_content) n'est pas renvoyé au client via callback
   • Les informations sensibles telles que les ID de fournisseur (supplier_ids) ont été filtrées
   • Les champs de facturation internes (cost10000, sender_cost10000) ne sont pas renvoyés via callback

3. Exigences de réception

   • L'interface de callback du client doit renvoyer une réponse dans un délai de 5 secondes
   • Elle doit renvoyer un code de statut HTTP 200 ou 204 pour indiquer une réception réussie
   • Si d'autres codes de statut sont renvoyés ou en cas d'expiration du délai, le système effectue automatiquement de nouvelles tentatives

4. Mécanisme de nouvelle tentative

   • De nouvelles tentatives sont effectuées automatiquement après l'échec d'un callback
   • L'intervalle entre les tentatives augmente progressivement
   • Les données sont conservées dans Redis pendant la période des tentatives

5. Description des horodatages

   • itime : horodatage du moment où le callback s'est produit, en secondes
   • msg_time : horodatage de création du message, en secondes
   • delivered_time : champ spécifique à Kwai, horodatage de livraison, en millisecondes

6. Paramètres personnalisés

   • Le champ custom_args renvoie tels quels les paramètres personnalisés transmis lors de l'envoi du message
   • Si aucun paramètre personnalisé n'a été transmis lors de l'envoi, ce champ n'apparaît pas dans les données de callback

Référence des codes d'erreur

Description des codes d'erreur courants (pour les codes d'erreur spécifiques, veuillez vous référer à la documentation des codes d'erreur) :

Pour une description plus détaillée des codes d'erreur, veuillez vous référer à la documentation distincte des codes d'erreur.

Journal des modifications

• 2024-01 : version initiale
• Ajout du champ kwai_extra pour prendre en charge les clients Kwai
• Filtrage des champs d'informations sensibles pour renforcer la sécurité