Callback-API

Übersicht

Nachrichtenstatus-Daten werden an das Unternehmenssystem zurückgemeldet, um eine statistische Auswertung zu ermöglichen.

Callback-Adresse

Das Unternehmen muss eine Callback-Adresse (alternativ: Callback-URL) zum Empfang von Nachrichtenstatus-Änderungen festlegen. Aktuell gibt es hierfür keine Web-Oberfläche. Bitte wenden Sie sich an das technische Personal von Engagelab, um die Callback-Adresse einzurichten.

Überprüfung der Gültigkeit der Callback-Adresse

Bei der Konfiguration der Callback-Adresse im Push-Backend unter Anwendungseinstellungen wird eine POST-Anfrage mit einem zufällig generierten, 8-stelligem String als echostr-Parameter im Request-Body gesendet. Sie müssen den Wert von echostr im Response-Body zurückgeben, wie im folgenden Format:

Request Body:

              
              {
    "echostr": "12345678"
}

            

Response Body:

              
              12345678

            

Sicherheitsmechanismus

Optional zur Client-Authentifizierung.

Um sicherzustellen, dass die Nachrichten tatsächlich von Engagelab stammen, können Sie die Authentizität der POST-Daten überprüfen. Alternativ können Sie die POST-Daten auch ohne Authentifizierung direkt auswerten.

Die Authentifizierung erfolgt wie folgt:

• Konfigurieren Sie in der Engagelab-Konsole einen Benutzernamen für den Callback (username) sowie ein Callback-Geheimnis (secret) für die Callback-Adresse.

Lesen Sie X-CALLBACK-ID aus dem Request-Header, wie im folgenden Beispiel:

              
              X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c4451207a16b

            

Erklärung der Parameter:

• timestamp ist der Zeitstempel der Callback-Nachricht (im Standardformat),
• nonce ist eine Zufallszahl,
• signature ist die Signaturinformation.

Die Signatur wird wie folgt gebildet:

              
              signature=HMAC-SHA256(secret, timestamp+nonce+username)

            

Antwortmechanismus

Nach Erhalt des Callbacks von Engagelab muss innerhalb von 3 Sekunden wie folgt geantwortet werden:

• Erfolgreicher Empfang: Der HTTP-Statuscode muss 200 oder 204 sein, eine Antwortnachricht ist nicht erforderlich.
• Fehlgeschlagener Empfang: Der HTTP-Statuscode muss 5XX oder 4XX sein und eine Antwortnachricht enthalten. Das Format lautet:

              
              {
    "code": 2002,
    "message": "error"
}

            

Callback-Felder im Detail

Nachrichtenkörper

Felder des rows-Arrays

Felder des status-Objekts

Nachrichtenstatus: Werte und Bedeutung

Callback-Inhalt und Beispiele

Callback-Methode: POST
Content-Type: application/json

Callback-Beispiel

Request Header

              
              POST /developer_define_url HTTP/1.1
Content-Type: application/json

            

Request Body

              
              {
    "total": 1,
    "rows": [
        {
            "message_id": "1666165485030094861", // Nachrichten-ID bei EngageLab (message_id)
            "from": "", // Absender
            "to": "", // Empfänger, registrationID
            "server": "AppPush",
            "channel": "FCM",
            "custom_args": {}, // Die beim Erstellen der Nachricht übergebenen Parameter
            "itime": 1640707579, // z. B. Zeitpunkt der Zustellung
            "status": {
                // Felder bei Erfolg
                "message_status": "delivered", // Nachrichtenstatus    
                "status_data": { // Benutzerdefinierte Daten
                    "channel_message_id": "wamid.123321abcdefed==", // Optional, Nachrichten-ID des Drittanbieterkanals
                    "ntf_msg": 1, // Nachrichtentyp
                    "platform": "a", // Push-Plattform
                    "uid": 100, // Nutzer-ID für die Push-Nachricht    
                    "app_version": "", // SDK-integrierte App-Version 
                    "channel": "", // SDK-integrierter App-Kanal   
                    "msg_time": 1640707579, // Zeitpunkt der Zustellung
                    "time_zone": "+8", // Zeitzone der Organisation 
                    "loss_valid_type": 0, // Ohne Bedeutung
                    "plan_user_total": 0, // Ohne Bedeutung 
                    "callback_type": 0 // Ohne Bedeutung
                },
                // Felder bei Fehler
                "error_code": 0, // Fehlercode - entsprechend dem Lifecycle-Fehlercode
                "error_detail": {
                    "message": "" // Fehlerursache
                },
                "loss": {
                    "loss_source": "vivo",
                    "loss_step": 1
                } // Verluststufe und -quelle
            }
        }
    ]
}

            

Parameterbeschreibung und Werte

Verluststufen und Bedeutung

1. Plan-Ziele → Gültige Ziele
2. Gültige Ziele → Gesendet
3. Gesendet → Zugestellt
4. Zugestellt → Klicks

Wichtige Hinweise:

1. Klicks und Zustellungen können auf manchen Kanälen doppelt gezählt werden. Führen Sie ggf. eine eigene Duplikatsbereinigung durch.
2. Die Zustell- und Anzeigeanzahl wird 5 Tage nach erfolgreicher Zustellung nicht mehr angepasst.