Vorlagenverwaltung

Die Vorlagenverwaltung mit der Verify API ermöglicht es Ihnen, die Nachricht, die zur Übermittlung eines OTP an Ihre Benutzer gesendet wird, individuell anzupassen, anstatt die Standardvorlagen von Vonage zu verwenden. Benutzerdefinierte Vorlagen können für SMS und Sprache für alle unterstütztes Gebietsschema.

Struktur der Vorlage

Benutzerdefinierte Vorlagen sind in zwei Teile unterteilt:

• Die template - einen eindeutigen Namen hat und eine ID enthält, und ob es sich um die Standardvorlage handelt. Eine Vorlage wird bei der Erstellung immer auf Standard gesetzt und kann später geändert werden.

• template_fragments - eine Vorlage kann viele Fragmente haben, die einzigartige Kombinationen von locale und channelDamit können Sie benutzerdefinierte Vorlagen in mehreren Sprachen für einen einzelnen Kanal erstellen. Sie enthalten eine ID, die Vorlagennachricht und Zeitstempel, wann sie erstellt und aktualisiert wurden.

Bei der Erstellung von Fragmenten können Sie vier statische Variablen innerhalb des Nachrichtentextes verwenden. Die einzige erforderliche Variable, die die Nachricht enthalten muss, ist der Code, der im Text durch ${code}.

Eine Vorlage erstellen

Um eine Vorlage zu erstellen, senden Sie eine

curl -X POST https://api.nexmo.com/v2/verify/templates \
-H "Content-Type: application/json" \
-H "Authorization: Bearer XXXXX" \
-d '{"name": "my-template"
}'

In der Antwort erhalten Sie eine template_idzusammen mit einigen Links, über die Sie Ihre Vorlage und ihre Fragmente nach der Erstellung ansehen können:

{
   "template_id": "8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9",
   "name": "my-template",
   "is_default": true,
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v2/verify/templates/8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9"
      },
      "fragments": {
         "href": "https://api.nexmo.com/v2/verify/templates/8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9/template_fragments"
      }
   }
}

Die erste benutzerdefinierte Vorlage, die Sie erstellen, wird automatisch als Standardvorlage festgelegt, wie durch is_default = true. Um dies zu ändern, siehe Aktualisieren einer Vorlage.

Als nächstes müssen Sie Fragmente für jedes Gebietsschema und jeden Kanal erstellen, für die Sie eine benutzerdefinierte Nachricht verwenden möchten.

Fragmente erstellen

Um ein Fragment zu erstellen, müssen Sie eine

curl -X POST https://api.nexmo.com/v2/verify/templates/:template_id/template_fragments \
-H "Content-Type: application/json" \
-H "Authorization: Bearer XXXXX" \
-d '{
   "channel": "sms",
   "locale": "en-gb",
   "text": "Thank you for continuing to use ${brand}! Your OTP is: ${code}"
}

Im Hauptteil dieser Anfrage:

• channel gibt den Kanal an, für den dieses Fragment bestimmt ist, und muss einer der folgenden sein sms oder voice.
• locale ist der Gebietsschema-Code der Sprache, in der die Nachricht verfasst ist. Zum Beispiel, en-gb ist Englisch (UK) und de-de ist deutsch.
• text ist die Nachricht, die Sie senden möchten. Diese muss enthalten die ${code} Variable. Weitere optionale statische Variablen, die Sie aufnehmen können, sind:
  • ${brand} - Wird durch den Wert des Parameters "brand" der Verify-Anfrage ersetzt.
  • ${time-limit} - Wird durch die Zeitspanne (Number) ersetzt, nach der der Code als abgelaufen gilt.
  • ${time-limit-unit} - wird durch die Zeiteinheit (Sekunden, Minuten) des Pincode-Verfallsbetrags ersetzt (time-limit).

Diese Anfrage erstellt eine Vorlage für eine SMS, die an eine Person im Vereinigten Königreich gesendet wird. Um eine Version dieser Nachricht zu erstellen, die z. B. an eine Person in Frankreich gesendet werden soll, würden Sie eine weitere

curl -X POST https://api.nexmo.com/v2/verify/templates/:template_id/template_fragments \
-H "Content-Type: application/json" \
-H "Authorization: Bearer XXXXX" \
-d '{
   "channel": "sms",
   "locale": "fr-fr",
   "text": "Merci de continuer à utiliser ${brand}! Votre OTP est: ${code}"
}

Wie wählt Verify die zu verwendende Vorlage aus?

Um die für eine Anfrage zu verwendende Vorlage zu bestimmen, geht die Verify API wie folgt vor:

• Sobald eine Verify-Anfrage gesendet wurde, verwendet die API entweder ein in der Anfrage angegebenes Gebietsschema oder sie erkennt das Gebietsschema, an das die Anfrage gesendet wird.
  • Um den Standort zu ermitteln, verwendet Verify die angegebene Telefonnummer, um festzustellen, wo sich die Person befindet. Zum Beispiel, 447700900000 wird abgebildet auf en-gb da es sich um eine britische Nummer handelt, während 847700900000 wird abgebildet auf fr-fr da es sich um eine französische Nummer handelt.
  • Wenn eine Nachricht in einer bestimmten Sprache gesendet werden soll, verwenden Sie die Option locale Parameter in Ihrer Anfrage. Dies kann in Ländern wie Kanada nützlich sein, wo es mehrere Amtssprachen gibt.

Sobald es das zu verwendende Gebietsschema ermittelt hat, sucht Verify nach einer Vorlage, die diesem Gebietsschema entspricht:

• Wenn Sie eine template_id in Ihrer Anfrage angeben, wird zuerst diese Vorlage betrachtet und geprüft, ob Sie eine benutzerdefinierte Vorlage für dieses Gebietsschema und diesen Kanal erstellt haben. Ist eine solche vorhanden, wird die OTP-Nachricht unter Verwendung dieser Vorlage gesendet.
• Wenn eine solche nicht existiert oder wenn Sie keine Angabe gemacht haben template_id in der Anfrage, wird Verify versuchen, eine Standardvorlage für dieses Gebietsschema zu verwenden.
  • Wenn Sie eine benutzerdefinierte Vorlage erstellt haben, wird versucht, eine Vorlage zu verwenden, die is_default auf true gesetzt.
  • Andernfalls wird versucht, eine Standardvorlage von Vonage zu verwenden.
• Wenn keine Vorlage für dieses Gebietsschema gefunden wird oder Sie ein nicht unterstütztes Gebietsschema in diesem Kanal verwenden, wird standardmäßig en_US.

Der gesamte Ablauf ist im Folgenden dargestellt:

Andere Vorlagenoperationen

Ausführliche Informationen zu allen Vorlagenvorgängen finden Sie in der API-Spezifikation verifizierenmit Beispielen für Anfragen und Antworten. Sie sind auch unten zusammengefasst:

Anzeigen von Vorlagen

Sie können alle von Ihnen erstellten Vorlagen auflisten, indem Sie eine

https://api.nexmo.com/v2/verify/templates

Sie können auch eine bestimmte Vorlage anzeigen, indem Sie eine

https://api.nexmo.com/v2/verify/templates/:template_id

Aktualisieren einer Vorlage

Sie können die name Ihrer Vorlage sowie die Angabe, ob es sich um die Standardvorlage handelt, indem Sie die Option is_default Parameter. Senden Sie dazu eine PATCH Anfrage an diesen Endpunkt und ersetzt dabei :template_id mit der ID der Vorlage, die Sie aktualisieren:

curl -X PATCH https://api.nexmo.com/v2/verify/templates/:template_id \
-H "Content-Type: application/json" \
-H "Authorization: Bearer XXXXX" \
-d '{
   "name": "my-template-updated",
   "is_default": false
}

Löschen einer Vorlage

Löschen Sie eine Vorlage, indem Sie eine

https://api.nexmo.com/v2/verify/templates/:template_id

Andere Operationen mit Vorlagenfragmenten

Ausführliche Informationen zu allen Vorlagenvorgängen finden Sie in der API-Spezifikation verifizierenSie werden jedoch auch im Folgenden zusammengefasst:

Anzeigen von Vorlagenfragmenten

Sie können alle Vorlagenfragmente auflisten, die Sie für eine bestimmte Vorlage erstellt haben, indem Sie eine

https://api.nexmo.com/v2/verify/templates/:template_id/template_fragments

Stellen Sie sicher, dass Sie die :template_id mit der ID der Vorlage, für die Sie die Fragmente sehen möchten.

Um eine bestimmte Vorlage anzuzeigen, senden Sie eine

https://api.nexmo.com/v2/verify/templates/:template_id/template_fragments/:template_fragment_id

Aktualisieren eines Vorlagenfragments

Sie können die mit Ihrem Vorlagenfragment gesendete Nachricht aktualisieren, indem Sie die text Parameter. Das Gebietsschema und der Kanal können nicht aktualisiert werden.

Senden Sie dazu eine PATCH Anfrage an diesen Endpunkt und ersetzt dabei :template_id und :template_fragment_id mit Ihrer Vorlagen-ID und Vorlagenfragment-ID:

curl -X PATCH https://api.nexmo.com/v2/verify/templates/:template_id/template_fragments/:template_fragment_id \
-H "Content-Type: application/json" \
-H "Authorization: Bearer XXXXX" \
-d '{
   "text": "The authentication code for your ${brand} is: ${code}"
}

Löschen eines Vorlagenfragments

Löschen Sie ein Vorlagenfragment, indem Sie eine

https://api.nexmo.com/v2/verify/templates/:template_id/template_fragments/:template_fragment_id

Fehlersuche

Hier sind einige häufige Fehler, die bei der Verwendung von benutzerdefinierten Vorlagen auftreten können:

• Der Account ist nicht aktiviert: Während Lesevorlagen allen Nutzern zur Verfügung stehen, muss das Schreiben von benutzerdefinierten Vorlagen in Ihrem Account aktiviert sein. Bitte wenden Sie sich an Ihren Account Manager oder an den Support, um diese Funktion zu aktivieren.
• Vorlage oder Fragment vorhanden: Jede Vorlage muss einen eindeutigen Namen haben, und jedes Fragment auf dieser Vorlage muss ein kombinierter eindeutiger Eintrag für ein Gebietsschema und einen Kanal sein.
• Versuch, eine Vorlage mit Fragmenten zu löschen: Sie können eine Vorlage nicht löschen, wenn sie bereits Fragmente enthält. Sie können die HAL-Felder für die Erkennung in der Antwort auf "get template", um die IDs der vorhandenen zu löschenden Fragmente zu durchsuchen, bevor die Vorlage selbst gelöscht wird.
• Nicht verwenden ${code} im Text: Wenn Sie ein Fragment erstellen, müssen Sie den Code in den Text einfügen.
• Maximale Anzahl von Vorlagen: Es gibt eine Obergrenze von 10 Vorlagen pro Benutzer, und der Versuch, mehr zu erstellen, führt zu einem Fehler.