OTP senden

Diese Schnittstelle dient dazu, einen Verifizierungscode von der EngageLab-Plattform generieren zu lassen und ihn gemäß der in der Vorlage festgelegten Kanalstrategie zu senden.

Wenn Sie den Verifizierungscode lieber selbst generieren möchten, statt ihn von der EngageLab-Plattform generieren zu lassen, können Sie die Schnittstelle EngageLab OTP – Benutzerdefiniertes OTP senden aufrufen.

Anfrage-URL

POST https://otp.api.engagelab.cc/v1/messages

Authentifizierung

Bitte lesen Sie Authentifizierung, um zu erfahren, wie Sie die API-Authentifizierung durchführen.

Anfragebeispiel

Anfrage-Header

              
              POST /v1/messages  HTTP/1.1  
Content-Type: application/json  
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0

            

Anfragetext

              
              {
    "to": "+6591234567",
    "template":{
      "id":"test-template-1",
      "language": "default",
        "params": {
        "key1": "value1",
        "key2": "value2"
        }
    }
}

            

Anfrageparameter

Ein Anfrageobjekt wird im JSON-Format ausgedrückt, daher muss der Anfrage-Header Content-Type: application/json enthalten.

Hinweise zu params

1. Für in der Vorlage voreingestellte Felder wie from_id gilt: Wenn der Feldwert in params nicht übergeben wird, wird beim Senden der Nachricht das voreingestellte from_id der Vorlage verwendet;
2. Wird ein Feldwert in params übergeben, z. B. params:{"from_id":"12345"}, wird das from_id der Vorlage beim Senden der Nachricht durch 12345 ersetzt;
3. Gleichzeitig werden auch benutzerdefinierte Variablenfelder im Vorlageninhalt, die beim Erstellen der Vorlage festgelegt wurden, über params mit Werten belegt. Wenn der Vorlageninhalt beispielsweise Hi {{name}}, your verify code is {{code}} lautet, müssen Sie den Parameter params:{"name":"Bob"} zuweisen.
4. Spezielle Variablen des Email-Kanals: Für den Email-Kanal können Sie über params den E-Mail-Betreff (subject), den Absendernamen (from_name), die Absender-E-Mail (from_mail) usw. dynamisch überschreiben. Ausführliche Hinweise zur erweiterten Verwendung finden Sie unter Vorlage erstellen – Erweiterte Verwendung von E-Mail-Vorlagenvariablen.

Antwortparameter

Erfolgsantwort

              
              {
    "message_id": "1725407449772531712",
    "send_channel": "sms"
}

            

Beachten Sie, dass der zurückgegebene Wert send_channel nicht den endgültig an den Benutzer zugestellten Kanal darstellt, sondern nur den in dieser Phase verwendeten Kanal; wenn zum Beispiel die in der Vorlage konfigurierte Strategie vorsieht, dass nach einem fehlgeschlagenen WhatsApp-Versand automatisch auf den SMS-Kanal zurückgegriffen wird, gibt die Schnittstelle den Wert whatsapp zurück. Nachdem das System den Zustellfehler nach einer gewissen Zeit erkannt hat, verwendet es den SMS-Kanal zum Senden.

Fehlerantwort

Der HTTP-Statuscode ist 4xx oder 5xx, und der Antworttext enthält die folgenden Felder:

              
              {
    "code": 5001,
    "message": "sms send fail"
}

            

Fehlercodes

Die folgende Tabelle beschreibt nur Fehler, die diese API während der Authentifizierung, der Vorabprüfung vor dem Versand und der synchronen Übermittlung zurückgibt. Asynchrone Zustellfehler nach Annahme durch den Anbieter werden von dieser API nicht zurückgegeben; rufen Sie sie über die Nachrichtenstatusabfrage oder Callbacks ab.

Aufrufer sollten code verwenden, um den Fehlertyp zu bestimmen. message dient zur Anzeige des konkreten Grunds oder zur Fehlersuche; verlassen Sie sich nicht auf festen message-Text für die Geschäftslogik.

Hinweise zu Ratenbegrenzungs- und Sendervolumenfehlern

• 3004 ist die Vorlagen-Ratenkontrolle für OTP-Versand; das Limitfenster richtet sich nach der Vorlagenkonfiguration und entspricht nicht unbedingt der Gültigkeitsdauer des Verifizierungscodes.
• 6001 und 6002 sind Sicherheitsratenkontrollen auf Nummer- oder Endbenutzer-IP-Ebene.
• 6003 und 6008 bedeuten, dass diese Anfrage ein Sendervolumenlimit ausgelöst hat; nach Erreichen des Limits und Eintritt in den Aussetzungszustand können nachfolgende Anfragen 6007 zurückgeben.
• Bei HTTP 429 nicht sofort fortlaufend erneut versuchen; später erneut versuchen und bei anhaltendem Auftreten einen Administrator oder den technischen Support kontaktieren.
• 5011 bis 5019 decken nur Fehler ab, die in der synchronen Übermittlungsphase erkennbar sind. Status wie leere Nummern, ausgeschaltete Telefone oder Ablehnungen durch den Netzbetreiber nach Annahme durch den Anbieter können weiterhin über asynchronen Nachrichtenstatus oder Callbacks zurückgegeben werden.