Verify Templates (vérifier les modèles)
Les messages que l'API Verify envoie au cours du processus de vérification sont créés à l'aide d'un modèle. Des modèles par défaut sont fournis. Vous pouvez créer vos propres modèles pour personnaliser le contenu des SMS ou des messages vocaux que l'API Verify envoie en votre nom, afin de créer une expérience entièrement personnalisée pour vos utilisateurs.
Si vous souhaitez continuer à utiliser les modèles par défaut, aucune autre configuration n'est nécessaire et vous pouvez ignorer ce guide.
Modèles par défaut
Par défaut, l'API Verify utilise les modèles suivants :
{
"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."
}
Dans le modèle ci-dessus, ${pin}, ${brand} et ${pin_expiry} sont variables du modèle.
Variables de modèle
Vous pouvez utiliser les variables suivantes dans tous les modèles Verify :
${pin}: un espace réservé pour le code de vérification aléatoire${brand}le nom de votre entreprise ou de votre application${pin_expiry}: durée de validité du code de vérification, en secondes
Les ${pin} est généré aléatoirement par l'API Verify. Les valeurs de ${brand} et ${pin_expiry} sont les paramètres que vous avez définis dans votre appel à Verify request.
Les <break time="1s" /> est un Langage de balisage de la synthèse vocale (SSML) tag. Elle ajoute un délai d'une seconde avant la lecture du message de synthèse vocale.
Création d'un modèle personnalisé
Pour créer un modèle personnalisé, vous devez d'abord le définir au format JSON, puis registre il.
Le tableau suivant répertorie les paramètres que vous pouvez utiliser dans vos modèles personnalisés :
| Paramètres | Description | Exigée |
|---|---|---|
action_type | Les valeurs possibles sont les suivantes : sms - envoyer un message texte ou voice - envoyer un message de synthèse vocale | Oui |
lg | Spécifie le lieu utilisé pour délivrer des messages de vérification par synthèse vocale dans la langue, l'accent et le sexe de votre choix. Tous les appels vers Verify request pour un modèle personnalisé doit utiliser le même lg. Si vous souhaitez utiliser une langue non standard, vous devez fournir des liens vers des fichiers audio dans votre modèle, comme indiqué dans l'exemple "Langue personnalisée". ici. | Oui |
template | Le contenu affiché dans un message SMS (lorsque l'option action_type est sms) ou à votre utilisateur lors d'un appel de synthèse vocale (lorsque l'option action_type est voice). Ce contenu peut comprendre variables.Si vous donnez une valeur à template et action_type est voicene pas spécifier digit_n, welcome_message ou bye_message. | Non |
type | L'encodage utilisé pour les template lorsque le action_type est sms. Les valeurs possibles sont les suivantes : unicode ou text | Non |
digit_n | URL du fichier multimédia lu lorsque Vonage lit un chiffre à l'utilisateur à l'aide de la synthèse vocale. Si vous spécifiez digit_nvous devez également spécifier welcome_message et bye_message. Vonage insère le code de vérification entre les deux. | Non |
welcome_message | URL du fichier multimédia lu au début de l'appel. | Oui, si vous précisez digit_n |
bye_message | URL du fichier multimédia lu à la fin de l'appel. | Oui, si vous précisez digit_n |
contact_email | Définissez l'adresse e-mail utilisée pour générer un ticket Zendesk et activer votre modèle personnalisé. Si vous ne définissez pas ce paramètre, Verify utilise l'adresse e-mail associée à votre clé API principale. | Non |
Exemples de modèles personnalisés
Voici quelques exemples de modèles :
{
"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"
}
Enregistrement d'un modèle personnalisé
Faire la demande
Après avoir défini le modèle, vous devez l'enregistrer auprès de l'API Verify. Pour ce faire, vous devez envoyer une demande à l'API https://api.nexmo.com/verify/templates avec le modèle comme charge utile.
Les exemples de code suivants vous montrent comment enregistrer votre modèle personnalisé :
<?php
//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 = array('Content-Type: application/json', 'Accept: application/json') ;
//Create the payload for an SMS custom template
$payload = json_encode([
"action_type" => "sms",
"lg" => "en-gb",
"contact_email" => "xyz@example.com",
"template" => "Your ${brand} verification code is ${pin}"
]);
//Create the request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
$response = curl_exec($ch);
echo $response;
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)
require "net/http"
require "uri"
require "json"
#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
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}"
}.to_json
uri = URI( url )
req = Net::HTTP::Post.new(uri.request_uri, headers)
req.body = payload
response = Net::HTTP.start(uri.host, uri.port,
:use_ssl => uri.scheme == 'https') {|http| http.request req}
case response
when Net::HTTPSuccess
puts "success" + response.body
else
puts "Error" + response.body
end
Comprendre la réponse
La réponse JSON se présente comme suit :
{
"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"
}
L'en-tête de la réponse contient l'un des codes d'état HTTP suivants :
- [201] - Votre modèle personnalisé a été créé
- [400] - Votre demande contient des paramètres incorrects ou Vonage n'a pas pu télécharger les médias que vous avez spécifiés dans votre modèle.
- [401] - Le
api_key/api_secretL'Account que vous avez utilisé dans votre demande n'était pas valide ou votre compte a été désactivé. - [500] - Erreur interne.
Le corps de la réponse contient les clés et les valeurs suivantes :
| Clé | Valeur |
|---|---|
account_id | Votre api_key. |
action_type | Les valeurs possibles sont les suivantes : sms - Modèle de SMS ou voice - Le modèle vocal a été utilisé |
bye_message | L'ID du fichier multimédia lu à la fin de l'appel. |
digit_n | Les ID des fichiers médias utilisés pour chaque chiffre. |
lg | Le modèle lieu. |
status | Statut actuel du modèle dans le système. Les valeurs possibles sont les suivantes : ACTIVE - en cours d'utilisation, PENDING - en attente d'approbation et d'activation ou RETIRED - n'est plus actif |
template | Le message qui sera envoyé à l'utilisateur sous forme de SMS ou d'appel à la synthèse vocale. |
type | Le codage utilisé pour le modèle lorsque l'option action_type est sms. Les valeurs possibles sont les suivantes : unicode ou text (par défaut) |
version | Le numéro de version du modèle. Ce numéro est généré automatiquement. |
welcome_message | L'ID du fichier multimédia lu au début de l'appel. |