Callback-Einstellungen

Die Callback-Einstellungen ermöglichen es Ihnen, die Callback-Adressen Ihres Geschäftssystems zu konfigurieren, um Echtzeit-Events wie „Nachrichtenstatus“ und „Nachrichtenantwort“ vom EngageLab SMS-Dienst zu erhalten. Durch die Nutzung von Callbacks können Sie das Nachrichten-Tracking automatisieren, Wiederholungsstrategien implementieren und Systembenachrichtigungen auslösen. Zudem steigern Sie so die Effizienz und Intelligenz der Nachrichtenverarbeitung.

• Nachrichtenstatus: Bezieht sich auf Statusänderungen einzelner SMS-Nachrichten in verschiedenen Phasen wie Versand, Zustellung, Lesebestätigung und Verifizierung.
• Nachrichtenantwort: Bezieht sich auf Inhalte und Events von Nutzer:innen-Antworten (Uplink-Nachrichten).

Callback-Liste

Die Callback-Liste zeigt alle konfigurierten Callback-Informationen sowie deren Gesundheitsstatus für eine zentrale Verwaltung und Wartung an.

• Suchfeld: Unterstützt die Echtzeit-Filterung nach Callback-Beschreibung, um Ziel-Callbacks schnell zu finden.
• Callback konfigurieren: Klicken Sie auf die Schaltfläche, um den Einrichtungsprozess für neue Callbacks zu starten und flexibel weitere Anforderungen zu ergänzen.

Feldbeschreibungen

Callback konfigurieren

Klicken Sie oben rechts auf die Schaltfläche [Callback konfigurieren], um zur Konfigurationsseite zu gelangen.

Wie im obigen Bild gezeigt, füllen Sie die Felder wie „Callback-Beschreibung“, „Callback-URL“, „Benutzername“, „Authentifizierung“, „Callback-Events“ und „Nachrichtenantwort“ aus.

• Wählen Sie Callback-Events aus, um bei Auftreten der gewählten Events Informationen an Ihre konfigurierte Callback-Adresse zu senden.
• Klicken Sie rechts auf die Optionen für Nachrichtenstatus und Nachrichtenantwort, um entsprechende Beispiele einzusehen.

Konfigurationsprozess

Beim Konfigurieren der Callback-Adresse wird eine HTTP-POST-Anfrage an die angegebene Adresse gesendet. Der zugehörige Entwicklerservice muss innerhalb von 3 Sekunden mit dem HTTP-Statuscode 200 antworten; andernfalls wird die Adresse als ungültig betrachtet.

• Der Entwicklerservice muss lediglich mit dem HTTP-Statuscode 200 antworten, ein Response-Body ist nicht erforderlich.

Beispiel für eine Anfrage

Angenommen, die konfigurierte Callback-Adresse lautet https://example.engagelabSMS.callback.com, wird folgende leere Nutzlast an die Adresse gesendet. Dargestellt mit dem curl-Befehl:

              
              curl -X POST https://example.engagelabSMS.callback.com -d ''

            

Beispiel für eine Antwort

Der Entwicklerservice zur Callback-Adresse muss nur mit dem HTTP-Statuscode 200 antworten, wie unten gezeigt:

              
              HTTP/1.1 200 OK
Content-Length: 0

            

Callback-Konfiguration

• Benutzernamen-Konfiguration
  Dieser Schritt ist optional. Wenn ein Benutzername gesetzt wird, muss auch ein geheimer Schlüssel angegeben werden.

  Um die Echtheit der Nachrichtenquelle als EngageLab zu gewährleisten, können Sie die Authentizität der POST-Daten prüfen.

  Nach der Konfiguration von Benutzername und geheimem Schlüssel enthält die von EngageLab gesendete Anfrage den HTTP-Header: X-CALLBACK-ID.
  Der Wert von X-CALLBACK-ID ist:
  timestamp={timestamp};nonce={nonce};username={username};signature={signature}

  Beispiel:

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

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

  Diesen Codeblock im schwebenden Fenster anzeigen
  • timestamp: Zeitstempel der Callback-Nachricht (im Standardformat).
  • nonce: Eine Zufallszahl.
  • signature: Die Signaturinformation, berechnet wie folgt:
    signature=HMAC-SHA256(secret, timestamp+nonce+username)

  Nachfolgend ein Python-Beispiel zur Signaturprüfung:

  import hashlib, hmac def verify(username, secret, timestamp, nonce, signature): return signature == hmac.new( key=secret.encode(), msg='{}{}{}'.format(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='{}{}{}'.format(timestamp, nonce, username).encode(),
          digestmod=hashlib.sha256
      ).hexdigest()
  
              

  Diesen Codeblock im schwebenden Fenster anzeigen

• Authentifizierungs-Konfiguration
  Dieser Schritt ist optional. Wenn Ihre Callback-Adresse eine Authentifizierung für die Anfragen von EngageLab erfordert, geben Sie hier die Zugangsdaten an. EngageLab fügt diesen Authorization-Header den Anfragen hinzu.

Callback-Request-Body

Wenn ein Callback-Event ausgelöst wird, sendet das EngageLab SMS-System Daten an die Callback-Adresse.

Beispiel für „Nachrichtenstatus“-Anfrage

Nachrichtenstatus:

• plan (geplant zum Versand)
• sent (erfolgreich versendet)
• sent_failed (Versand fehlgeschlagen)
• delivered (erfolgreich zugestellt)
• delivered_failed (Zustellung fehlgeschlagen)

              
              {
    "total": 2,
    "rows": [
        {
            "message_id": "1742442805608914944",
            "to": "+8615989574757",
            "server": "SMS",
            "channel": "SMS",
            "itime": 1704265712,
            "status": {
                "message_status": "plan",
                "status_data": {
                    "msg_time": 1704265712,
                    "message_id": "1742442805608914944",
                    "template_key": "auto_create_templateu25az170295320745",
                    "business_id": "100917676394736"
                },
                "error_code": 0
            }
        },
        {
            "message_id": "1742442805608914944",
            "to": "+8615989574757",
            "server": "SMS",
            "channel": "SMS",
            "itime": 1704265712,
            "status": {
                "message_status": "sent_failed",
                "status_data": {
                    "msg_time": 1704265712,
                    "message_id": "1742442805608914944",
                    "template_key": "auto_create_templateu25az170295320745",
                    "business_id": "100917676394736"
                },
                "error_code": 5001,
                "error_detail": {
                    "message": "sender config is invalid"
                }
            }
        }
    ]
}

            

Beispiel für „Nachrichtenantwort“-Anfrage

Event:

• uplink_message (Uplink-Nachricht)

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