Lebenszyklus-Status-Callback-Schnittstelle

Dieses Dokument beschreibt die Datenstruktur und Feldbeschreibungen der Callback-Schnittstelle für den Lebenszyklusstatus von Nachrichten. Das System sendet die Statusinformationen per HTTP POST an die vom Kunden konfigurierte URL, wenn sich der Nachrichtenstatus ändert.

Callback-Methode

• Anfragemethode: POST
• Content-Type: application/json
• Erfolgsantwort: HTTP-Statuscode 200 oder 204
• Wiederholung bei Fehler: Gibt der Kunde keinen Erfolgsstatuscode zurück, wiederholt das System den Versuch automatisch

Datenstruktur

1. Äußere Struktur (ReportLifecycles)

              
              {
  "total": 1,
  "rows": [
    {
      // ReportLifecycle object array
    }
  ]
}

            

2. ReportLifecycle-Objekt

Die Struktur jedes Elements im Array rows ist wie folgt:

3. Status-Objekt

Objekt mit Statusdetails:

Hinweis: Die folgenden Felder werden für interne Statistiken verwendet und nicht an den Kunden zurückgemeldet:

• analysis - Internes statistisches Analysefeld

4. StatusData-Objekt

Statusbezogene Basisdaten:

Hinweis: Die folgenden Felder sind sensible Informationen oder interne Felder, wurden gefiltert und werden nicht an den Kunden zurückgemeldet:

• message_content - Nachrichteninhalt (sensible Information)
• parts - Anzahl der Nachrichtenfragmente (internes Feld)
• msg_type - Nachrichtentyp (internes Feld)
• protocol_type - Protokolltyp (internes Feld)
• supplier_ids - Anbieter-ID (sensible Information)

5. Billing-Objekt

Abrechnungsinformationen (werden nur zurückgegeben, wenn Abrechnungsdaten vorliegen):

Hinweis: Die folgenden Felder sind interne Abrechnungsfelder und werden nicht an den Kunden zurückgemeldet:

• cost10000 - Internes Abrechnungsfeld (Einheit 1/10000)
• sender_cost10000 - Absenderkosten (Einheit 1/10000)

6. ErrorDetail-Objekt

Fehlerdetails (werden nur bei einem Fehler zurückgegeben):

7. KwaiExtra-Objekt

Kwai-kundenspezifische Erweiterungsinformationen (werden nur im Status delivered und für Kwai-Kunden zurückgegeben):

Beschreibung des Nachrichtenstatus

Gängige Werte für den Nachrichtenstatus:

Callback-Beispiele

Beispiel 1: Nachricht erfolgreich zugestellt

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

            

Beispiel 2: Versand der Nachricht fehlgeschlagen

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

            

Beispiel 3: Zustellung der Nachricht fehlgeschlagen (mit Abrechnungsinformationen)

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

            

Beispiel 4: Sprachnachricht eines Kwai-Kunden zugestellt

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

            

Hinweise

1. Regeln für die Feldrückgabe

   • Alle als omitempty markierten Felder erscheinen nicht im zurückgegebenen JSON, wenn der Wert leer oder null ist
   • Sensible Informationen und interne Felder wurden vor dem Callback gefiltert oder gelöscht

2. Sicherheit

   • Der Nachrichteninhalt (message_content) wird nicht an den Kunden zurückgemeldet
   • Sensible Informationen wie Anbieter-IDs (supplier_ids) wurden gefiltert
   • Interne Abrechnungsfelder (cost10000, sender_cost10000) werden nicht zurückgemeldet

3. Empfangsanforderungen

   • Die Callback-Schnittstelle des Kunden muss innerhalb von 5 Sekunden eine Antwort zurückgeben
   • Sie muss den HTTP-Statuscode 200 oder 204 zurückgeben, um den erfolgreichen Empfang anzuzeigen
   • Werden andere Statuscodes zurückgegeben oder tritt eine Zeitüberschreitung auf, wiederholt das System den Versuch automatisch

4. Wiederholungsmechanismus

   • Nach einem fehlgeschlagenen Callback wird der Versuch automatisch wiederholt
   • Das Wiederholungsintervall vergrößert sich schrittweise
   • Die Daten werden während des Wiederholungszeitraums in Redis gespeichert

5. Beschreibung der Zeitstempel

   • itime: Zeitstempel, zu dem der Callback erfolgte, in Sekunden
   • msg_time: Zeitstempel, zu dem die Nachricht erstellt wurde, in Sekunden
   • delivered_time: Kwai-spezifisches Feld, Zustellzeitstempel, in Millisekunden

6. Benutzerdefinierte Parameter

   • Das Feld custom_args gibt die beim Senden der Nachricht übergebenen benutzerdefinierten Parameter unverändert zurück
   • Werden beim Senden keine benutzerdefinierten Parameter übergeben, erscheint dieses Feld nicht in den Callback-Daten

Fehlercode-Referenz

Beschreibungen gängiger Fehlercodes (für konkrete Fehlercodes siehe bitte die Fehlercode-Dokumentation):

Ausführlichere Beschreibungen der Fehlercodes finden Sie in der separaten Fehlercode-Dokumentation.

Änderungsprotokoll

• 2024-01: Erstversion
• Feld kwai_extra zur Unterstützung von Kwai-Kunden hinzugefügt
• Felder mit sensiblen Informationen gefiltert, um die Sicherheit zu erhöhen