Gestión de plantillas

La administración de plantillas con Verify API te permite personalizar el mensaje enviado para entregar una OTP a tus usuarios, en lugar de usar las plantillas predeterminadas de Vonage. Las plantillas personalizadas se pueden configurar para SMS y voz a través de cualquier configuración regional admitida.

Estructura de plantillas

Las plantillas personalizadas se dividen en dos partes:

• En template - tiene un nombre único y contiene un ID, y si es la plantilla por defecto. Una plantilla siempre se establece como predeterminada cuando se crea y puede cambiarse posteriormente.

• template_fragments - una plantilla puede tener muchos fragmentos, que son combinaciones únicas de locale y channelle permite crear plantillas personalizadas en varios idiomas para un mismo canal. Contienen un ID, el mensaje de la plantilla y marcas de tiempo de creación y actualización.

Al crear fragmentos, puede utilizar cuatro variables estáticas dentro del texto del mensaje. La única variable obligatoria que debe contener el mensaje es el código, que se representa en el texto mediante ${code}.

Crear una plantilla

Para crear una plantilla, envíe una solicitud

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

En la respuesta, recibirá un template_idjunto con algunos enlaces que pueden utilizarse para ver su plantilla y sus fragmentos una vez creados:

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

La primera plantilla personalizada que cree se establecerá automáticamente como plantilla predeterminada, como indica is_default = true. Para modificarlo, consulte Actualizar una plantilla.

A continuación, tendrá que crear fragmentos para cada configuración regional y canal en los que desee utilizar un mensaje personalizado.

Creación de fragmentos

Para crear un fragmento, tendrá que enviar una solicitud

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

En el cuerpo de esta solicitud:

• channel especifica el canal para el que es este fragmento, y debe ser uno de los siguientes sms o voice.
• locale es el código de configuración regional del idioma en el que está escrito el mensaje. Por ejemplo, en-gb es inglés (UK) y de-de es alemán.
• text es el mensaje que desea enviar. Este debe contienen el ${code} variable. Otras variables estáticas opcionales que puedes incluir son:
  • ${brand} - Se sustituirá por el valor del parámetro "marca" de la solicitud de verificación.
  • ${time-limit} - Será sustituido por la cantidad de tiempo (número) antes de que el código se considere caducado.
  • ${time-limit-unit} - se sustituirá por la unidad de tiempo (segundos, minutos) del importe de caducidad del código pin (time-limit).

Esta solicitud creará una plantilla de mensaje para un SMS enviado a alguien en el Reino Unido. Para crear una versión de este mensaje que se enviaría a alguien en Francia, por ejemplo, usted enviaría otra solicitud

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

¿Cómo elige Verify qué plantilla utilizar?

Para determinar la plantilla que se utilizará para una solicitud, la API de Verify seguirá estos pasos:

• Una vez enviada una solicitud de Verify, la API utilizará la configuración regional especificada en la solicitud o detectará la configuración regional a la que se envía la solicitud.
  • Para detectar la localidad, Verify utiliza el número de teléfono facilitado para determinar dónde se encuentra la persona. Por ejemplo, 447700900000 se asignará a en-gb ya que es un número del Reino Unido, mientras que 847700900000 se asignará a fr-fr ya que es un número francés.
  • Si necesita que un mensaje se envíe en un idioma específico, utilice la opción locale en su solicitud. Esto puede ser útil en situaciones de países como Canadá, donde tienen varios idiomas oficiales.

Una vez determinada la configuración regional, Verify buscará una plantilla que se ajuste a dicha configuración:

• Si ha proporcionado un template_id en tu solicitud, mirará primero esa plantilla y comprobará si has creado una plantilla personalizada para esa configuración regional y canal. Si existe una, enviará el mensaje OTP utilizando esa plantilla.
• Si no existe, o si no proporcionó una template_id en la solicitud, Verify intentará utilizar una plantilla predeterminada para esa configuración regional.
  • Si ha creado una plantilla personalizada, intentará utilizar una que tenga is_default a verdadero.
  • De lo contrario, intentará utilizar una plantilla predeterminada de Vonage.
• Si no se puede encontrar una plantilla para esa configuración regional, o si está utilizando una configuración regional no compatible con ese canal, se utilizará por defecto la opción en_US.

A continuación se muestra el flujo completo:

Otras operaciones de plantilla

Encontrará información detallada sobre todas las operaciones de la plantilla en la sección Verify API Specification (Verificar especificación API)incluyendo ejemplos de solicitudes y respuestas. También se resumen a continuación:

Ver plantillas

Puede listar todas las plantillas que ha creado enviando una solicitud

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

O vea una plantilla específica enviando una solicitud

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

Actualizar una plantilla

Puede actualizar el name de su plantilla, junto con si la plantilla es la plantilla por defecto cambiando la opción is_default parámetro. Para ello, envíe un PATCH a este punto final, sustituyendo :template_id con el ID de la plantilla que está actualizando:

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
}

Borrar una plantilla

Elimine una plantilla enviando una solicitud

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

Otras operaciones de fragmentos de plantillas

Encontrará información detallada sobre todas las operaciones de la plantilla en la sección Verify API Specification (Verificar especificación API)No obstante, también se resumen a continuación:

Visualización de fragmentos de plantillas

Puede listar todos los fragmentos de plantilla que ha creado para una plantilla específica enviando una solicitud

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

Asegúrese de sustituir :template_id con el ID de la plantilla de la que desea ver los fragmentos.

Para ver una plantilla específica, envíe una solicitud

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

Actualización de un fragmento de plantilla

Puede actualizar el envío de mensajes utilizando su fragmento de plantilla actualizando el campo text parámetro. La configuración regional y el canal no se pueden actualizar.

Para ello, envíe un PATCH a este punto final, sustituyendo :template_id y :template_fragment_id con su ID de plantilla y su ID de fragmento de plantilla:

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

Borrar un fragmento de plantilla

Elimine un fragmento de plantilla enviando una solicitud

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

Solución de problemas

Estos son algunos errores comunes que puede encontrar al intentar utilizar plantillas personalizadas:

• La Account no está habilitada: Mientras que las plantillas de lectura están disponibles para todos los usuarios, la escritura de plantillas personalizadas debe estar habilitada en su Account. Póngase en contacto con su gestor de Account o hable con el servicio de asistencia para activar esta función.
• Plantilla o fragmento existente: Cada plantilla debe tener un nombre único, y cada fragmento de esa plantilla debe ser una entrada única combinada para una configuración regional y un canal.
• Intento de eliminar una plantilla con fragmentos: No puede eliminar una plantilla si tiene fragmentos existentes. Puede utilizar la función Campos HAL para el descubrimiento en la respuesta get template para recorrer los ID de los fragmentos existentes a eliminar antes de eliminar la plantilla en sí.
• No utilizar ${code} en el texto: Al crear un fragmento, debe incluir el código dentro del texto.
• Número máximo de plantillas: Hay un límite de 10 plantillas por usuario, y un intento de generar más dará lugar a un error.