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."
}

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
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í.
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} です。"
}

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:

#!/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"

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"
}

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_secret combinació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.