Logo Site EngageLab Mark Colored TransparentDokumentation
SMS
Doku-Startseite
DokumentationAPI-Referenz
Suchen
Anmelden
API-Referenz/Callback-Ereignisreferenz
API-ReferenzCallback-Ereignisreferenz...

Callback-Ereignisreferenz

Zuletzt aktualisiert：5 days ago

Konfiguration und Verifizierung der Callback-URL

Nach der Konfiguration der Callback-URL sendet EngageLab SMS automatisch eine HTTP-POST-Anfrage an diese URL, um die Verfügbarkeit der Schnittstelle zu überprüfen. Ihr Dienst muss innerhalb von 3 Sekunden einen HTTP-Statuscode 200 zurückgeben, andernfalls betrachtet das System die URL als nicht verfügbar.

Hinweis:
Um sicherzustellen, dass Sie Callback-Daten ordnungsgemäß empfangen können, fügen Sie bitte 119.8.170.74 und 114.119.180.30 zur Firewall-Whitelist Ihres Servers hinzu.

Anfragebeispiel

Angenommen, Ihre Callback-URL lautet https://example.engagelabSMS.callback.com, sendet das System die folgende Anfrage:

curl -X POST https://example.engagelabSMS.callback.com -d '{}'
              
              curl -X POST https://example.engagelabSMS.callback.com -d '{}'
Diesen Codeblock im schwebenden Fenster anzeigen

Antwortanforderungen

Ihr Dienst muss lediglich einen HTTP-Statuscode 200 ohne Inhalt zurückgeben. Zum Beispiel:

HTTP/1.1 200 OK Content-Length: 0
              
              HTTP/1.1 200 OK
Content-Length: 0
Diesen Codeblock im schwebenden Fenster anzeigen

Hinweis:
Die Verifizierung der Callback-URL prüft nur den HTTP-Statuscode und erfordert nicht die Rückgabe eines bestimmten Payload-Inhalts. Stellen Sie sicher, dass Ihre Dienstschnittstelle innerhalb von 3 Sekunden korrekt mit einem 200 antworten kann.

Sicherheitsmechanismen für Callbacks

Um die Sicherheit und vertrauenswürdige Herkunft der Callback-Daten zu gewährleisten, unterstützt EngageLab SMS mehrere Methoden zur Sicherheitsprüfung.

Verifizierung über Benutzername und Secret (optional)

  • Optionale Konfiguration. Wenn ein Benutzername festgelegt wird, muss auch ein Secret festgelegt werden.
  • Nach der Konfiguration fügt EngageLab jeder Callback-Anfrage im HTTP-Header das Feld X-CALLBACK-ID im folgenden Format hinzu:
X-CALLBACK-ID: timestamp={timestamp};nonce={nonce};username={username};signature={signature}
              
              X-CALLBACK-ID: timestamp={timestamp};nonce={nonce};username={username};signature={signature}
Diesen Codeblock im schwebenden Fenster anzeigen
  • Dabei gilt:
    • timestamp: Zeitstempel beim Senden des Callbacks
    • nonce: Zufallszahl
    • username: Der von Ihnen konfigurierte Benutzername
    • signature: Signaturinformation, wie folgt berechnet

Methode zur Signaturberechnung (Python-Beispiel)

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()
Diesen Codeblock im schwebenden Fenster anzeigen
  • Der Server kann die Legitimität der Callback-Anfrage mit der oben beschriebenen Methode überprüfen.

Authorization-Authentifizierung (optional)

  • Wenn Ihre Callback-Schnittstelle eine Authentifizierung erfordert (z. B. Basic Auth, Bearer Token usw.), können Sie die Authorization-Informationen während der Konfiguration eintragen.
  • EngageLab fügt dieses Authorization-Feld bei der Anfrage automatisch hinzu, sodass Ihr Dienst die Identität der Anfrage leicht überprüfen kann.

Erläuterungen zu Callback-Ereignissen

Nachrichtenstatus

Der Nachrichtenstatus dient dazu, die Statusänderungen jeder Nachricht über ihren gesamten Lebenszyklus hinweg zu verfolgen. Er bietet Echtzeit-Einblick in den Fortschritt von Versand, Zustellung und Verifizierung und erleichtert statistische Analysen, Ausnahmebehandlung und die Optimierung der Benutzererfahrung.

Ereigniskennung Beschreibung
plan Nachricht zum Versand geplant, gelangt in die Warteschlange
target_valid Zielnummer ist gültig
target_invalid Zielnummer ist ungültig
sent Nachricht erfolgreich gesendet
sent_failed Versand der Nachricht fehlgeschlagen
delivered Nachricht an das Gerät des Nutzers zugestellt
delivered_failed Nachricht gesendet, aber Zustellung an das Gerät fehlgeschlagen

Callback-Datenstruktur

Äußere Struktur

{ "total": 1, "rows": [ { // ReportLifecycle object } ] }
              
              {
  "total": 1,
  "rows": [
    {
      // ReportLifecycle object
    }
  ]
}
Diesen Codeblock im schwebenden Fenster anzeigen
Feldname Typ Beschreibung
total int Anzahl der Datensätze in diesem Callback
rows array Array mit Lebenszyklus-Statusdaten

ReportLifecycle-Objekt

Feldname Typ Beschreibung
message_id string Eindeutige Nachrichten-ID
to string Empfängernummer
server string Diensttyp (z. B. SMS)
channel string Kanaltyp
itime int64 Callback-Zeitstempel (Sekunden)
custom_args object Benutzerdefinierte Argumente (zurückgegeben, falls übergeben)
status object Statusdetailobjekt

status-Objekt

Feldname Typ Beschreibung
message_status string Aktueller Status der Nachricht (siehe Tabelle unten)
status_data object Statusdatenobjekt
billing object Abrechnungsinformationsobjekt (zurückgegeben, falls abgerechnet)
error_code int Fehlercode, 0 bedeutet kein Fehler
error_detail object Fehlerdetails (zurückgegeben, wenn ein Fehler auftritt)

status_data-Objekt

Feldname Typ Beschreibung
msg_time int64 Zeitstempel der Nachrichtenerstellung (Sekunden)
message_id string Nachrichten-ID
current_send_channel string Name des aktuellen Sendekanals
template_key string Key der Vorlagenkonfiguration
business_id string Business-ID
plan_id string Plan-ID

billing-Objekt (zurückgegeben, falls abgerechnet)

Feldname Typ Beschreibung
cost float64 Kostenbetrag
currency string Währung, fest auf "USD"

In der Regel enthalten nur Nachrichten in der sent-Phase Abrechnungsinformationen.

error_detail-Objekt (zurückgegeben, wenn ein Fehler auftritt)

Feldname Typ Beschreibung
message string Beschreibung der Fehlermeldung

Beispiel: Nachricht erfolgreich gesendet

{ "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
      }
    }
  ]
}
Diesen Codeblock im schwebenden Fenster anzeigen

Beispiel: 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", "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"
        }
      }
    }
  ]
}
Diesen Codeblock im schwebenden Fenster anzeigen

Nachrichtenbenachrichtigung

Nachrichtenbenachrichtigungen beziehen sich auf systembezogene Geschäftsereignisse oder Warnungen. Sie dienen dazu, das Unternehmen auf den Betriebszustand des Dienstes, das Guthaben, die Prüfung von Vorlagen und andere wichtige Informationen aufmerksam zu machen und erleichtern so eine zeitnahe Bearbeitung und Risikowarnung.

Ereigniskennung Beschreibung
template_audit_result Benachrichtigung über das Ergebnis der Vorlagenprüfung

Nachrichtenantwort

Nachrichtenantworten beziehen sich hauptsächlich auf Callback-Antwortereignisse bei der Interaktion mit Nutzern oder externen Systemen.

Ereigniskennung Beschreibung
uplink_message Inhalt von Antwortnachrichten, die Nutzer per SMS o. Ä. senden

Beispiel

{ "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!"
                }
            }
        }
    ]
}
Diesen Codeblock im schwebenden Fenster anzeigen

Systemereignisse

Systemereignisse umfassen betriebliche Vorgänge im Zusammenhang mit Konten, Vorlagen, API-Aufrufen usw. Sie erleichtern die Überwachung, Prüfung und automatisierte Verarbeitung zentraler Vorgänge wie Kontoanmeldungen, Schlüsseländerungen, API-Aufrufe usw.

Ereigniskennung Beschreibung
account_login Benachrichtigung über Vorgänge im Zusammenhang mit der Kontoanmeldung
key_manage Benachrichtigung über Schlüsseländerungen, -verwaltung usw.
template_manage Benachrichtigung über das Hinzufügen, Ändern, Löschen usw. von Vorlagen
api_call Benachrichtigung über Vorgänge im Zusammenhang mit API-Schnittstellenaufrufen

Callback-Datenstruktur

Äußere Struktur

{ "total": 1, "rows": [ { // System event object } ] }
              
              {
  "total": 1,
  "rows": [
    {
      // System event object
    }
  ]
}
Diesen Codeblock im schwebenden Fenster anzeigen
Feld Typ Beschreibung
total int64 Gesamtzahl der Ereignisse in diesem Callback
rows array Array von Systemereignisobjekten

Systemereignisobjekt

Feld Typ Beschreibung
server string Fest auf "SMS"
itime int64 Zeitstempel des Ereigniseintritts (Sekunden)
system_event object Inhalt des Systemereignisses

system_event-Objekt

Feld Typ Beschreibung
event string Ereignistyp
data object Ereignisdaten

data-Objekt

Feld Typ Beschreibung
business_id string Business-ID
org_id string Organisations-ID
operator object Informationen zum Bediener

operator-Objekt

Feld Typ Beschreibung
email string E-Mail des Bedieners (falls vorhanden)
api_key string API Key (falls vorhanden)
ip_address string IP des Vorgangs

Anfragestruktur

{ "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"
          }
        }
      }
    }
  ]
}
Diesen Codeblock im schwebenden Fenster anzeigen

Kontoanmeldungsereignis

Feld Typ Beschreibung
action string Anmeldung erfolgreich/Anmeldung fehlgeschlagen/Abmeldung
fail_reason string Grund für fehlgeschlagene Anmeldung, nur bei login_failed zurückgegeben

Beispiel

{ "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"
    }
  }
}
Diesen Codeblock im schwebenden Fenster anzeigen

Vorlagenverwaltungsereignis

Feld Typ Beschreibung
action string Vorlage erstellen/Vorlage aktualisieren/Vorlage löschen
template_id string Vorlagen-ID
template_name string Vorlagenname

Beispiel

{ "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"
    }
  }
}
Diesen Codeblock im schwebenden Fenster anzeigen

Schlüsselverwaltungsereignis

Feld Typ Beschreibung
action string Schlüssel erstellen/Schlüssel aktualisieren/Schlüssel löschen/Schlüssel ansehen
api_key string API Key
description string Beschreibung (optional)

Beispiel

{ "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": "Create key" } } }
              
              {
  "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": "Create key"
    }
  }
}
Diesen Codeblock im schwebenden Fenster anzeigen

API-Aufrufereignis

Feld Typ Beschreibung
api_path string API-Pfad
method string HTTP-Methode

Beispiel

{ "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"
    }
  }
}
Diesen Codeblock im schwebenden Fenster anzeigen
Icon Solid Transparent White Qiyu
Vertrieb kontaktieren