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, voz y RCS a través de cualquier configuración regional admitida.

Estructura de plantillas

Las plantillas personalizadas se dividen en dos partes:

• El template - Tiene un nombre único y contiene un identificador, además de indicar si se trata de la plantilla predeterminada. Una plantilla siempre se establece como predeterminada al crearse y se puede cambiar posteriormente.

• template_fragments - Una plantilla puede tener muchos fragmentos, que son combinaciones únicas de locale y channel; esto te permite crear plantillas personalizadas en varios idiomas para un mismo canal. Contienen un identificador, el texto de la plantilla y las marcas de tiempo de su 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ía una solicitud POST al templates endpoint. En el cuerpo de la solicitud, tendrá que proporcionar un nombre para la plantilla:

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_id, junto con algunos enlaces que puedes utilizar para ver tu 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 cambiar esto, consulta Actualización de una plantilla.

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

Creación de fragmentos

Para crear un fragmento, tendrá que enviar una solicitud POST al archivo template_fragments punto final. Debe sustituir :template_id con el template_id que recibió al crear su plantilla:

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, voice, o rcs.
• 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 (Reino Unido) y de-de es alemán.
• text es el mensaje que quieres enviar. Esto debe contener 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 POST con el campo fr-fr y una configuración regional text mensaje:

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 configuración regional, Verify utiliza el número de teléfono facilitado para determinar dónde se encuentra la persona. Por ejemplo, 447700900000 se corresponderá con en-gb ya que es un número del Reino Unido, mientras que 847700900000 se corresponderá con 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 parámetro en tu solicitud. Esto puede resultar útil en países como Canadá, donde hay varios idiomas oficiales.

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

• Si has facilitado un template_id En tu solicitud, el sistema consultará primero esa plantilla y comprobará si has creado una plantilla personalizada para esa configuración regional y ese canal. Si existe alguna, 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 has 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 proceso completo:

Otras operaciones de plantilla

Se puede consultar información detallada sobre todas las operaciones de las plantillas en el Verify la especificación de la APIincluyendo ejemplos de solicitudes y respuestas. También se resumen a continuación:

Visualización de plantillas

Puedes ver una lista de todas las plantillas que has creado enviando una solicitud GET a este punto final:

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

O bien, puedes ver una plantilla concreta enviando una solicitud GET al mismo punto final con el ID de tu plantilla:

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

Actualización de 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 envía una solicitud 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 DELETE a este punto final, sustituyendo :template_id con el ID de la plantilla que vas a eliminar:

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

Otras operaciones con fragmentos de plantilla

Se puede consultar información detallada sobre todas las operaciones de las plantillas en el Verify la especificación de la APINo 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 GET a este punto final:

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

Asegúrese de sustituir :template_id con el ID de la plantilla cuyos fragmentos quieras ver.

Para ver una plantilla específica, envíe una solicitud GET al mismo punto final con su ID de plantilla y su ID de fragmento de plantilla:

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. No es posible actualizar la configuración regional ni el canal.

Para ello, envíe un PATCH envía una solicitud 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}"
}

Cómo eliminar un fragmento de plantilla

Para eliminar un fragmento de plantilla, envía una solicitud DELETE a este punto final, sustituyendo :template_id y :template_fragment_id con su ID de plantilla y su ID de fragmento de plantilla:

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, debes 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.