Vorlagen verifizieren

Die Nachrichten, die die Verify API während des Verifizierungsprozesses sendet, werden mithilfe einer Vorlage erstellt. Es werden Standardvorlagen bereitgestellt. Sie können Ihre eigenen Vorlagen erstellen, um den Inhalt aller SMS- oder Sprachnachrichten, die die Verify API in Ihrem Namen sendet, anzupassen und so ein vollständig markengerechtes Erlebnis für Ihre Benutzer zu schaffen.

Wenn Sie weiterhin die Standardvorlagen verwenden möchten, ist keine weitere Konfiguration erforderlich und Sie können diese Anleitung ignorieren.

Standardvorlagen

Standardmäßig verwendet die Verify-API die folgenden Vorlagen:

{
  "action_type": "voice",
  "lg": "en-gb",
  "template": "<break time='1s' /> Please enter your ${brand} activation code ${pin}, I repeat ${pin}, valid the next ${pin_expiry} minutes."
}

{
  "action_type": "sms",
  "lg": "en-us",
  "template": "${brand} code: ${pin}. Valid for ${pin_expiry} minutes."
}

In der obigen Vorlage, ${pin}, ${brand} und ${pin_expiry} sind Template-Variablen.

Template-Variablen

Sie können die folgenden Variablen in allen Verify-Vorlagen verwenden:

${pin}: ein Platzhalter für den zufälligen Verifizierungscode
${brand}: der Name Ihres Unternehmens oder Ihrer Anwendung
${pin_expiry}Dauer der Gültigkeit des Verifizierungscodes (in Sekunden)

Die ${pin} wird von der Verify-API nach dem Zufallsprinzip generiert. Die Werte für ${brand} und ${pin_expiry} sind die Parameter, die Sie in Ihrem Aufruf an Anfrage verifizieren.

Die <break time="1s" /> ist eine Sprachsynthese-Auszeichnungssprache (SSML) Tag. Es fügt eine Verzögerung von einer Sekunde hinzu, bevor die Text-to-Speech-Nachricht abgespielt wird.

Erstellen einer benutzerdefinierten Vorlage

Um eine benutzerdefinierte Vorlage zu erstellen, müssen Sie sie zunächst im JSON-Format definieren und dann registrieren es.

In der folgenden Tabelle sind die Einstellungen aufgeführt, die Sie in Ihren benutzerdefinierten Vorlagen verwenden können:

Parameter	Beschreibung	Erforderlich
`action_type`	Mögliche Werte sind: `sms` - eine Textnachricht senden oder `voice` - eine Text-to-Speech-Nachricht senden	Ja
`lg`	Spezifiziert die Standort verwendet, um Text-zu-Sprache-Bestätigungsnachrichten in der von Ihnen gewählten Sprache, dem von Ihnen gewählten Akzent und Geschlecht zu übermitteln. Alle Anrufe an Anfrage verifizieren für eine benutzerdefinierte Vorlage muss die gleiche `lg`. Wenn Sie ein nicht standardisiertes Gebietsschema verwenden möchten, müssen Sie in Ihrer Vorlage Links zu Audiodateien angeben, wie im Beispiel "Benutzerdefiniertes Gebietsschema" gezeigt hier.	Ja
`template`	Der in einer SMS-Nachricht angezeigte Inhalt (wenn die `action_type` ist `sms`) oder in einem Text-to-Speech-Anruf zu Ihrem Benutzer gesprochen (wenn die `action_type` ist `voice`). Dieser Inhalt kann Folgendes umfassen Variablen. Wenn Sie einen Wert für `template` und `action_type` ist `voice`, nicht angeben `digit_n`, `welcome_message` oder `bye_message`.	Nein
`type`	Die Kodierung, die für `template` wenn die `action_type` ist `sms`. Mögliche Werte sind: `unicode` oder `text`	Nein
`digit_n`	URL zu der Mediendatei, die abgespielt wird, wenn Vonage dem Benutzer eine Ziffer mit Text-to-Speech vorliest. Wenn Sie angeben `digit_n`sollten Sie auch Folgendes angeben `welcome_message` und `bye_message`. Vonage fügt den Verifizierungscode zwischen den beiden ein.	Nein
`welcome_message`	URL zu der Mediendatei, die zu Beginn des Anrufs abgespielt wird.	Ja, wenn Sie Folgendes angeben `digit_n`
`bye_message`	URL zu der Mediendatei, die am Ende des Anrufs abgespielt wird.	Ja, wenn Sie Folgendes angeben `digit_n`
`contact_email`	Legen Sie die E-Mail-Adresse fest, die zum Generieren eines Zendesk-Tickets und zum Aktivieren Ihrer benutzerdefinierten Vorlage verwendet wird. Wenn Sie diesen Parameter nicht festlegen, verwendet Verify die E-Mail-Adresse, die mit Ihrem Master-API-Schlüssel verknüpft ist.	Nein

Beispiele für benutzerdefinierte Vorlagen

Im Folgenden finden Sie Beispiele für Vorlagen:

{
  "action_type": "voice",
  "lg": "ja-jp",
  "contact_email" : "xyz@example.com",
  "template": "あなたの ${brand}コードは ${pin} です。 繰り返します。 あなたの ${brand}コードは ${pin} です。"
}

{
  "action_type" : "sms",
  "lg" : "ru-ru",
  "type" : "unicode",
  "contact_email" : "xyz@example.com",
  "template" : "Ваш код подтверждения ${pin}"
}

{
  "action_type": "voice",
  "lg": "en_ie",
  "contact_email" : "xyz@example.com",
  "welcome_message": "https://example.com/welcome.wav",
  "digit_0": "https://example.com/message_zero.wav",
  "digit_1": "https://example.com/message_one.wav",
  "digit_2": "https://example.com/message_two.wav",
  "digit_3": "https://example.com/message_three.wav",
  "digit_4": "https://example.com/message_four.wav",
  "digit_5": "https://example.com/message_five.wav",
  "digit_6": "https://example.com/message_six.wav",
  "digit_7": "https://example.com/message_seven.wav",
  "digit_8": "https://example.com/message_eight.wav",
  "digit_9": "https://example.com/message_nine.wav",
  "bye_message": "https://example.com/bye.wav"
}

Registrierung einer benutzerdefinierten Vorlage

Den Antrag stellen

Nachdem Sie die Vorlage definiert haben, müssen Sie sie bei der Verify-API registrieren. Dazu stellen Sie eine Anfrage an die https://api.nexmo.com/verify/templates Endpunkt, mit der Vorlage als Nutzlast.

Die folgenden Codebeispiele zeigen Ihnen, wie Sie Ihre benutzerdefinierte Vorlage registrieren können:

#!/bin/bash #Connection information base_url='https://api.nexmo.com' version='' action='/verify/templates' #Authentication information api_key='API_KEY' api_secret='API_SECRET' #Create the request URL url="${base_url}${version}${action}?api_key=${api_key}&api_secret=${api_secret}" #Create the custom template payload='{ "action_type" : "sms", "lg" : "en-gb", "contact_email" : "xyz@example.com", "template" : "Your ${brand} verification code is ${pin}" }' curl -X POST $url \ -H "Content-Type: application/json" \ -H "accept: application/json" \ -d "$payload"

import json
import requests

#Connection information
base_url = 'https://api.nexmo.com'
version = ''
action = '/verify/templates'

#Authentication information
api_key = 'API_KEY'
api_secret = 'API_SECRET'

#Create the request URL
url = base_url + version + action + "?api_key=" + api_key + "&api_secret=" + api_secret

#Set the headers
headers = {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
}

#Change the to parameter to the number you want to call
payload = {
  "action_type" : "sms",
  "lg" : "en-gb",
  "contact_email" : "xyz@example.com",
  "template" : "Your ${brand} verification code is ${pin}"
}

response = requests.post( url , data=json.dumps(payload), headers=headers)

if (response.status_code == 201):
    print response.content
else:
    print( "Error: " + str(response.status_code) + " " +    response.content)

Die Reaktion verstehen

Die JSON-Antwort sieht wie folgt aus:

{
   "account_id": "xxxxxxxx",
   "action_type": "voice",
   "bye_message": "8114bd6c-2208-432b-a46e-0880465a8fbe",
   "digit_0": "8114bd6c-2208-432b-a46e-0880465a8fbe",
   "digit_1": "01d6cb89-424f-4525-828c-504e77c7d6d4",
   "digit_2": "4a90f626-093a-4663-9778-bcd90b1e98f2",
   "digit_3": "798f836e-7395-4d08-824f-af237f18954b",
   "digit_4": "b0edd7fa-0404-4512-a8a1-c1a0c47d3100",
   "digit_5": "de4b8a27-52ff-47be-8e44-8df6c7d669a6",
   "digit_6": "c33a9ef5-19c5-436e-b93c-09b32f7e87e9",
   "digit_7": "44242673-acbd-4351-a0fc-470f4d7b38e2",
   "digit_8": "03b16135-cf60-4ee1-b2a4-41ad897fba67",
   "digit_9": "71c451f4-fb0c-4dbc-b8cb-d7ad11becdce",
   "lg": "es-es",
   "status": "pending",
   "template": "this is the template. with a ${pin}",
   "type": "text",
   "version": 19,
   "welcome_message": "8114bd6c-2208-432b-a46e-0880465a8fbe"
}

{
    "account_id": "xxxxxxxx",
    "action_type": "sms",
    "lg": "en-gb",
    "version": 2,
    "status": "pending",
    "template": "${pin} is your ${brand} verification code.",
    "type": "text"
}

Der Antwort-Header enthält einen der folgenden HTTP-Statuscodes:

[201] - Ihre benutzerdefinierte Vorlage wurde erstellt
[400] - Ihre Anfrage enthält falsche Parameter oder Vonage konnte keine Medien hochladen, die Sie in Ihrer Vorlage angegeben haben.
[401] - Die api_key / api_secret Kombination, die Sie in Ihrer Anfrage verwendet haben, war ungültig oder Ihr Account wurde deaktiviert.
[500] - Interner Fehler.

Der Antwortkörper enthält die folgenden Schlüssel und Werte:

Schlüssel	Wert
`account_id`	Ihr `api_key`.
`action_type`	Mögliche Werte sind: `sms` - SMS-Vorlage oder `voice` - Sprachvorlage wurde verwendet
`bye_message`	Die ID der Mediendatei, die am Ende des Anrufs abgespielt wird.
`digit_n`	Die IDs der für jede Ziffer verwendeten Mediendateien.
`lg`	Die Vorlage Standort.
`status`	Der aktuelle Status der Vorlage im System. Mögliche Werte sind: `ACTIVE` - derzeit in Gebrauch, `PENDING` - die darauf warten, genehmigt und aktiviert zu werden oder `RETIRED` - nicht mehr aktiv
`template`	Die Nachricht, die in einer SMS oder einem Text-to-Speech-Anruf an Ihren Benutzer gesendet wird.
`type`	Die Kodierung, die für die Vorlage verwendet wird, wenn die `action_type` ist `sms`. Mögliche Werte sind: `unicode` oder `text` (Standard)
`version`	Die Versionsnummer der Vorlage. Diese Nummer wird automatisch generiert.
`welcome_message`	Die ID der Mediendatei, die zu Beginn des Anrufs abgespielt wird.