Template Management

Template Management with the Verify API allows you to customize the message sent to deliver an OTP to your users, rather than using the default Vonage templates. Custom templates can be configured for SMS and Voice across any supported locale.

Template Structure

Custom templates are split into two parts:

• The template - this has a unique name and contains an ID, and whether it is the default template. A template is always set to default when being created and can be changed later.

• template_fragments - a template can have many fragments, which are unique combinations of locale and channel; this allows you to create custom templates in multiple languages for a single channel. They contain an ID, the template message, and timestamps for when they were created and updated.

When creating fragments, you can use four static variables within the message text. The only required variable that the message must contain is the code, which is represented in the text by ${code}.

Create a Template

To create a template, send a

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

In the response, you'll receive a template_id, along with some links that can be used to view your template and its fragments once they're created:

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

The first custom template you create will automatically be set as your default template, as indicated by is_default = true. To change this, see Updating a Template.

Next, you'll need to create fragments for each locale and channel you want to use a custom message for.

Creating Fragments

To create a fragment, you'll need to send a

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

In the body of this request:

• channel specifies the channel this fragment is for, and must be one of sms or voice.
• locale is the locale code of the language the message is written in. For example, en-gb is English (UK) and de-de is German.
• text is the message you want to send. This must contain the ${code} variable. Other optional static variables you can include are:
  • ${brand} - Will be replaced by the "brand" parameter value of the verify request.
  • ${time-limit} - Will be replaced by the amount of time (number) before the code is considered expired.
  • ${time-limit-unit} - Will be replaced by the time unit (seconds, minutes) of the pin code expiration amount (time-limit).

This request will create a template message for an SMS sent to someone in the UK. To create a version of this message to be sent to someone in France, for example, you would send another

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

How does Verify choose which template to use?

To determine the template to be used for a request, the Verify API will follow these steps:

• Once a Verify request has been sent, the API will either use a specified locale given in the request, or detect the locale to which the request is being sent.
  • To detect the locale, Verify uses the phone number provided to determine where the person is located. For example, 447700900000 will map to en-gb as it is a UK number, whereas 847700900000 will map to fr-fr as it is a French number.
  • If you need a message to be sent in a specific language, use the locale parameter in your request. This can be useful in situations for countries such as Canada where they have multiple official languages.

Once it has determined the locale to use, Verify will then look for a template that matches that locale:

• If you've provided a template_id in your request, it will look at that template first and check if you have created a custom template for that locale and channel. If one is there, it will send the OTP message using that template.
• If one does not exist, or if you did not provide a template_id in the request, Verify will attempt to use a default template for that locale.
  • If you've created a custom template, it will attempt to use one that has is_default set to true.
  • Otherwise, it will attempt to use a Vonage default template.
• If a template cannot be found for that locale, or you are using an unsupported locale within that channel, it will then default to en_US.

The full flow is depicted below:

Other Template Operations

Full details of all the template operations can be found in the Verify API Specification, including example requests and responses. They are also summarized below:

Viewing Templates

You can list all the templates you have created by sending a

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

Or view a specific template by sending a

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

Updating a Template

You can update the name of your template, along with whether the template is the default template by changing the is_default parameter. To do so, send a PATCH request to this endpoint, replacing :template_id with the ID of the template you're updating:

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
}

Deleting a Template

Delete a template by sending a

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

Other Template Fragment Operations

Full details of all the template operations can be found in the Verify API Specification, however they are also summarized below:

Viewing Template Fragments

You can list all the template fragments you have created for a specific template by sending a

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

Make sure you replace :template_id with the ID of the template you want to see the fragments for.

To view a specific template, send a

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

Updating a Template Fragment

You can update the message send using your template fragment by updating the text parameter. The locale and channel cannot be updated.

To do so, send a PATCH request to this endpoint, replacing :template_id and :template_fragment_id with your template ID and template fragment ID:

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

Deleting a Template Fragment

Delete a template fragment by sending a

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

Troubleshooting

Here are some common errors you might encounter when trying to use custom templates:

• The account is not enabled: While reading templates are available to all users, writing custom templates needs to be enabled on your account. Please contact your account manager or talk to support to enable the feature.
• Template or fragment exists: Each template must have a unique name, and each fragment on that template must be a combined unique entry for a locale and channel.
• Attempting to delete a template with fragments: You cannot delete a template if it has existing fragments. You can use the HAL fields for discovery in the get template response to traverse the IDs of existing fragments to delete before deleting the template itself.
• Not using ${code} in the text: When creating a fragment, you must include the code within the text.
• Max number of templates: There is a cap of 10 templates per user, and an attempt to generate more will result in an error.