Gestion des modèles

La gestion des modèles avec l'API Verify vous permet de personnaliser le message envoyé pour délivrer un OTP à vos utilisateurs, plutôt que d'utiliser les modèles par défaut de Vonage. Les modèles personnalisés peuvent être configurés pour les SMS et les messages vocaux dans n'importe quel pays. locale prise en charge.

Structure du modèle

Les modèles personnalisés sont divisés en deux parties :

• Les template - ce modèle a un nom unique et contient un identifiant, et s'il s'agit du modèle par défaut. Un modèle est toujours défini par défaut lors de sa création et peut être modifié ultérieurement.

• template_fragments - un modèle peut avoir de nombreux fragments, qui sont des combinaisons uniques de locale et channel; cela vous permet de créer des modèles personnalisés dans plusieurs langues pour un seul canal. Ils contiennent un identifiant, le message du modèle et les dates de création et de mise à jour.

Lors de la création de fragments, vous pouvez utiliser quatre variables statiques dans le texte du message. La seule variable obligatoire que le message doit contenir est le code, qui est représenté dans le texte par ${code}.

Créer un modèle

Pour créer un modèle, envoyez une requête

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

Dans la réponse, vous recevrez un template_idainsi que des liens permettant de visualiser votre modèle et ses fragments une fois qu'ils ont été créés :

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

Le premier modèle personnalisé que vous créez sera automatiquement défini comme modèle par défaut, comme l'indique la mention is_default = true. Pour modifier cela, voir Mise à jour d'un modèle.

Ensuite, vous devrez créer des fragments pour chaque locale et canal pour lesquels vous souhaitez utiliser un message personnalisé.

Création de fragments

Pour créer un fragment, vous devez envoyer une requête

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

Dans le corps de cette demande :

• channel spécifie le canal pour lequel ce fragment est destiné et doit être l'un des canaux suivants sms ou voice.
• locale est le code régional de la langue dans laquelle le message est rédigé. Par exemple, en-gb est l'anglais (UK) et de-de est allemand.
• text est le message que vous souhaitez envoyer. Ce message doit contiennent les ${code} (variable statique). D'autres variables statiques facultatives peuvent être incluses :
  • ${brand} - sera remplacé par la valeur du paramètre "brand" de la demande de vérification.
  • ${time-limit} - sera remplacé par le temps (nombre) qui s'écoule avant que le code ne soit considéré comme expiré.
  • ${time-limit-unit} - sera remplacé par l'unité de temps (secondes, minutes) du montant de l'expiration du code pin (time-limit).

Cette demande permet de créer un modèle de message pour un SMS envoyé à une personne au Royaume-Uni. Pour créer une version de ce message à envoyer à une personne en France, par exemple, vous devez envoyer une autre demande

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

Comment Verify choisit-il le modèle à utiliser ?

Pour déterminer le modèle à utiliser pour une demande, l'API Verify suit les étapes suivantes :

• Une fois qu'une demande Verify a été envoyée, l'API utilise les paramètres régionaux spécifiés dans la demande ou détecte les paramètres régionaux auxquels la demande est envoyée.
  • Pour détecter le lieu, Verify utilise le numéro de téléphone fourni pour déterminer où se trouve la personne. Par exemple, Verify utilise le numéro de téléphone fourni pour déterminer où se trouve la personne, 447700900000 correspondra à en-gb car il s'agit d'un numéro britannique, alors que 847700900000 correspondra à fr-fr car il s'agit d'un numéro français.
  • Si vous souhaitez qu'un message soit envoyé dans une langue spécifique, utilisez la fonction locale dans votre demande. Cela peut s'avérer utile dans des pays tels que le Canada, où il existe plusieurs langues officielles.

Une fois qu'il a déterminé la langue locale à utiliser, Verify recherche un modèle correspondant à cette langue :

• Si vous avez fourni un template_id dans votre demande, il examinera d'abord ce modèle et vérifiera si vous avez créé un modèle personnalisé pour cette région et ce canal. Si c'est le cas, il enverra le message OTP en utilisant ce modèle.
• S'il n'en existe pas, ou si vous n'avez pas fourni de template_id dans la demande, Verify tentera d'utiliser un modèle par défaut pour cette locale.
  • Si vous avez créé un modèle personnalisé, il essaiera d'en utiliser un qui a le format is_default est fixé à true.
  • Sinon, il tentera d'utiliser un modèle par défaut de Vonage.
• Si aucun modèle n'est trouvé pour cette langue, ou si vous utilisez une langue non prise en charge dans ce canal, la valeur par défaut sera la suivante en_US.

Le flux complet est illustré ci-dessous :

Autres opérations sur les modèles

Les détails complets de toutes les opérations du modèle peuvent être trouvés dans la section Verify la spécification de l'APIy compris des exemples de demandes et de réponses. Elles sont également résumées ci-dessous :

Visualisation des modèles

Vous pouvez dresser la liste de tous les modèles que vous avez créés en envoyant une requête

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

Vous pouvez également consulter un modèle spécifique en envoyant une requête

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

Mise à jour d'un modèle

Vous pouvez mettre à jour le name de votre modèle, et si le modèle est le modèle par défaut en changeant la valeur de l'attribut is_default de l'Union européenne. Pour ce faire, envoyez un PATCH à ce point de contact, en remplaçant :template_id avec l'ID du modèle que vous mettez à jour :

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
}

Suppression d'un modèle

Supprimer un modèle en envoyant une requête

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

Autres opérations sur les fragments de modèle

Les détails complets de toutes les opérations du modèle peuvent être trouvés dans la section Verify la spécification de l'APICependant, elles sont également résumées ci-dessous :

Visualisation des fragments de modèle

Vous pouvez dresser la liste de tous les fragments de modèle que vous avez créés pour un modèle spécifique en envoyant une requête

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

Veillez à remplacer :template_id avec l'ID du modèle dont vous voulez voir les fragments.

Pour visualiser un modèle spécifique, envoyez une requête

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

Mise à jour d'un fragment de modèle

Vous pouvez mettre à jour le message envoyé à l'aide de votre fragment de modèle en mettant à jour l'élément text paramètre. La locale et le canal ne peuvent pas être mis à jour.

Pour ce faire, envoyez un PATCH à ce point de contact, en remplaçant :template_id et :template_fragment_id avec l'ID du modèle et l'ID du fragment du modèle :

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

Suppression d'un fragment de modèle

Supprimer un fragment de modèle en envoyant une requête

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

Dépannage

Voici quelques erreurs courantes que vous pouvez rencontrer lorsque vous essayez d'utiliser des modèles personnalisés :

• Le compte n'est pas activé: Alors que les modèles de lecture sont disponibles pour tous les utilisateurs, la rédaction de modèles personnalisés doit être activée sur votre Account. Veuillez contacter votre Account manager ou vous adresser à l'assistance pour activer cette fonctionnalité.
• Le modèle ou le fragment existe: Chaque modèle doit avoir un nom unique et chaque fragment de ce modèle doit être une entrée unique combinée pour une locale et un canal.
• Tentative de suppression d'un modèle avec des fragments: Vous ne pouvez pas supprimer un modèle s'il contient des fragments existants. Vous pouvez utiliser la fonction Champs HAL pour la découverte dans la réponse "get template" afin de parcourir les ID des fragments existants à supprimer avant de supprimer le modèle lui-même.
• Ne pas utiliser ${code} dans le texte: Lorsque vous créez un fragment, vous devez inclure le code dans le texte.
• Nombre maximal de modèles: Il y a une limite de 10 modèles par utilisateur, et toute tentative de générer plus de modèles entraînera une erreur.