Verificar plantillas
Los mensajes que la API Verify envía durante el proceso de verificación se crean utilizando una plantilla. Se proporcionan plantillas predeterminadas. Puede crear sus propias plantillas para personalizar el contenido de cualquier mensaje SMS o de voz que la API de Verify envíe en su nombre, para crear una experiencia totalmente personalizada para sus usuarios.
Si desea seguir utilizando las plantillas predeterminadas, no es necesaria ninguna configuración adicional y puede ignorar esta guía.
Plantillas por defecto
Por defecto, la API Verify utiliza las siguientes plantillas:
{
"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."
}
En la plantilla anterior, ${pin}, ${brand} y ${pin_expiry} son variables de plantilla.
Variables de plantilla
Puede utilizar las siguientes variables en cualquier plantilla Verify:
${pin}un marcador de posición para el código de verificación aleatorio${brand}el nombre de su empresa o aplicación${pin_expiry}duración de la validez del código de verificación, en segundos
En ${pin} es generado aleatoriamente por la API de Verify. Los valores de ${brand} y ${pin_expiry} son los parámetros que establece en su llamada a Verify request.
En <break time="1s" /> es un Lenguaje de marcado de síntesis de voz (SSML) etiqueta. Añade un retardo de un segundo antes de que se reproduzca el mensaje de texto a voz.
Crear una plantilla personalizada
Para crear una plantilla personalizada, primero debe definirla en formato JSON y después regístrese en eso.
La siguiente tabla enumera los ajustes que puede utilizar en sus plantillas personalizadas:
| Parámetro | Descripción | Requerido |
|---|---|---|
action_type | Los valores posibles son: sms - enviar un mensaje de texto o voice - enviar un mensaje de texto a voz | Sí |
lg | Especifica el localización utilizado para enviar mensajes de verificación de texto a voz en el idioma, el acento y el género que elija. Todas las llamadas a Verify request para una plantilla personalizada debe utilizar el mismo lg. Si desea utilizar una configuración regional no estándar, deberá incluir enlaces a archivos de audio en su plantilla, como se muestra en el ejemplo "Configuración regional personalizada". aquí. | Sí |
template | El contenido que aparece en un mensaje SMS (cuando el action_type es sms) o hablado a su usuario en una llamada de texto a voz (cuando el action_type es voice). Este contenido puede incluir variables.Si proporciona un valor para template y action_type es voiceno especifique digit_n, welcome_message o bye_message. | No |
type | La codificación utilizada para template cuando el action_type es sms. Los valores posibles son: unicode o text | No |
digit_n | URL del archivo multimedia que se reproduce cuando Vonage lee un dígito al usuario utilizando la función de texto a voz. Si especificas digit_ntambién debe especificar welcome_message y bye_message. Vonage inserta el código de verificación entre los dos. | No |
welcome_message | URL del archivo multimedia reproducido al inicio de la llamada. | Sí, si especifica digit_n |
bye_message | URL del archivo multimedia reproducido al final de la llamada. | Sí, si especifica digit_n |
contact_email | Establezca la dirección de correo electrónico utilizada para generar un ticket de Zendesk y activar su plantilla personalizada. Si no establece este parámetro, Verify utiliza la dirección de correo electrónico asociada con su clave API maestra. | No |
Ejemplos de plantillas personalizadas
A continuación se ofrecen ejemplos de plantillas:
{
"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"
}
Registrar una plantilla personalizada
Realizar la solicitud
Una vez definida la plantilla, debe registrarla en la API de Verify. Para ello, realice una solicitud a la API https://api.nexmo.com/verify/templates con la plantilla como carga útil.
Los siguientes ejemplos de código le muestran cómo registrar su plantilla personalizada:
<?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
Comprender la respuesta
La respuesta JSON tiene el siguiente aspecto:
{
"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"
}
La cabecera de respuesta contiene uno de los siguientes códigos de estado HTTP:
- [201] - Su plantilla personalizada ha sido creada
- [400] - Tu solicitud contiene parámetros incorrectos o Vonage no pudo cargar ningún medio que hayas especificado en tu plantilla.
- [401] - El
api_key/api_secretcombinación que utilizó en su solicitud no era válida o su Account ha sido desactivado. - [500] - Error interno.
El cuerpo de la respuesta contiene las siguientes claves y valores:
| Clave | Valor |
|---|---|
account_id | Su api_key. |
action_type | Los valores posibles son: sms - Plantilla SMS o voice - Se utilizó la plantilla de voz |
bye_message | El ID del archivo multimedia reproducido al final de la llamada. |
digit_n | Los ID de los archivos multimedia utilizados para cada dígito. |
lg | La plantilla localización. |
status | Estado actual de la plantilla en el sistema. Los valores posibles son: ACTIVE - actualmente en uso, PENDING - a la espera de ser aprobado y activado o RETIRED - ya no está activo |
template | El mensaje que se enviará al usuario en un SMS o en una Llamada de texto a voz. |
type | La codificación utilizada para la plantilla cuando el action_type es sms. Los valores posibles son: unicode o text (por defecto) |
version | El número de versión de la plantilla. Este número se genera automáticamente. |
welcome_message | ID del archivo multimedia reproducido al inicio de la llamada. |