Verify Templates

The messages that the Verify API sends during the verification process are created using a template. Default templates are provided. You can create your own templates to customize the content of any SMS or voice messages that the Verify API sends on your behalf, to create a fully branded experience for your users.

If you want to continue using the default templates then no further configuration is required and you can ignore this guide.

Default templates

By default, the Verify API uses the following templates:

{
  "action_type": "sms",
  "lg": "en-us",
  "template": "${brand} code: ${pin}. Valid for ${pin_expiry} minutes."
}

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

In the above template, ${pin}, ${brand} and ${pin_expiry} are template variables.

Template variables

You can use the following variables in any Verify templates:

${pin}: a placeholder for the random verification code
${brand}: the name of your company or application
${pin_expiry}: how long the verification code is valid for, in seconds

The ${pin} is generated randomly by the Verify API. The values for ${brand} and ${pin_expiry} are the parameters you set in your call to Verify request.

The <break time="1s" /> is a Speech Synthesis Markup Language (SSML) tag. It adds a one second delay before the text-to-speech message is played.

Creating a custom template

To create a custom template you must first define it in JSON format and then register it.

The following table lists the settings you can use in your custom templates:

Parameter	Description	Required
`action_type`	Possible values are: `sms` - send a text message or `voice` - send a text-to-speech message	Yes
`lg`	Specifies the locale used to deliver text-to-speech verification messages in your chosen language, accent and gender. All calls to Verify request for a custom template must use the same `lg`. If you want to use a non-standard locale, you must supply links to audio files in your template as shown in the "Custom Locale" example here.	Yes
`template`	The content displayed in an SMS message (when the `action_type` is `sms`) or spoken to your user in a text-to-speech call (when the `action_type` is `voice`). This content can include variables. If you provide a value for `template` and `action_type` is `voice`, do not specify `digit_n`, `welcome_message` or `bye_message`.	No
`type`	The encoding used for `template` when the `action_type` is `sms`. Possible values are: `unicode` or `text`	No
`digit_n`	URL to the media file played when Vonage reads out a digit to the user using text-to-speech. If you specify `digit_n`, you should also specify `welcome_message` and `bye_message`. Vonage inserts the verification code between the two.	No
`welcome_message`	URL to the media file played at the start of the call.	Yes, if you specify `digit_n`
`bye_message`	URL to the media file played at the end of the call.	Yes, if you specify `digit_n`
`contact_email`	Set the email address used to generate a Zendesk ticket and activate your custom template. If you do not set this parameter, Verify uses the email address associated with your master API key.	No

Custom template examples

The following are examples of templates:

{
  "action_type": "voice",
  "lg": "en_ie",
  "contact_email" : "xyz@example.com",
  "welcome_message": "https://example.com/welcome.wav",
  "digit_0": "https://example.com/message_zero.wav",
  "digit_1": "https://example.com/message_one.wav",
  "digit_2": "https://example.com/message_two.wav",
  "digit_3": "https://example.com/message_three.wav",
  "digit_4": "https://example.com/message_four.wav",
  "digit_5": "https://example.com/message_five.wav",
  "digit_6": "https://example.com/message_six.wav",
  "digit_7": "https://example.com/message_seven.wav",
  "digit_8": "https://example.com/message_eight.wav",
  "digit_9": "https://example.com/message_nine.wav",
  "bye_message": "https://example.com/bye.wav"
}

{
  "action_type" : "sms",
  "lg" : "ru-ru",
  "type" : "unicode",
  "contact_email" : "xyz@example.com",
  "template" : "Ваш код подтверждения ${pin}"
}

{
  "action_type": "voice",
  "lg": "ja-jp",
  "contact_email" : "xyz@example.com",
  "template": "あなたの ${brand}コードは ${pin} です。 繰り返します。 あなたの ${brand}コードは ${pin} です。"
}

Registering a custom template

Making the request

After you have defined the template, you need to register it with the Verify API. You do this by making a request to the https://api.nexmo.com/verify/templates endpoint, with the template as the payload.

The following code examples show you how to register your custom template:

#!/bin/bash#Connection informationbase_url='https://api.nexmo.com'version=''action='/verify/templates'#Authentication informationapi_key='API_KEY'api_secret='API_SECRET'#Create the request URLurl="${base_url}${version}${action}?api_key=${api_key}&api_secret=${api_secret}"#Create the custom templatepayload='{ "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"

<?php

//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;

//Set the headers
$headers =  array('Content-Type: application/json', 'Accept: application/json') ;

//Create the payload for an SMS custom template
$payload = json_encode([
  "action_type" => "sms",
  "lg" => "en-gb",
  "contact_email" => "xyz@example.com",
  "template" => "Your ${brand} verification code is ${pin}"
]);

//Create the request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

$response = curl_exec($ch);

echo $response;

import json
import requests

#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

#Set the headers
headers = {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
}

#Change the to parameter to the number you want to call
payload = {
  "action_type" : "sms",
  "lg" : "en-gb",
  "contact_email" : "xyz@example.com",
  "template" : "Your ${brand} verification code is ${pin}"
}

response = requests.post( url , data=json.dumps(payload), headers=headers)

if (response.status_code == 201):
    print response.content
else:
    print( "Error: " + str(response.status_code) + " " +    response.content)

require "net/http"
require "uri"
require "json"

#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

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

#Change the to parameter to the number you want to call
payload = {
  "action_type" => "sms",
  "lg" => "en-gb",
  "contact_email" => "xyz@example.com",
  "template" => "Your ${brand} verification code is ${pin}"
}.to_json

uri = URI( url )

req = Net::HTTP::Post.new(uri.request_uri, headers)
req.body = payload

response = Net::HTTP.start(uri.host, uri.port,
        :use_ssl => uri.scheme == 'https') {|http| http.request req}

case response
when Net::HTTPSuccess
  puts "success" +  response.body
else
  puts "Error" + response.body
end

Understanding the response

The JSON response looks like:

{
    "account_id": "xxxxxxxx",
    "action_type": "sms",
    "lg": "en-gb",
    "version": 2,
    "status": "pending",
    "template": "${pin} is your ${brand} verification code.",
    "type": "text"
}

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

The response header contains one of the following HTTP status codes:

[201] - Your custom template has been created
[400] - Your request contains incorrect parameters or Vonage could not upload any media that you specified in your template.
[401] - The api_key / api_secret combination you used in your request was invalid or your account has been disabled.
[500] - Internal error.

The response body contains the following keys and values:

Key	Value
`account_id`	Your `api_key`.
`action_type`	Possible values are: `sms` - SMS template or `voice` - Voice template was used
`bye_message`	The ID of the media file played at the end of the call.
`digit_n`	The IDs of the media files used for each digit.
`lg`	The template locale.
`status`	The template's current status in the system. Possible values are: `ACTIVE` - currently in use, `PENDING` - waiting to be approved and activated or `RETIRED` - no longer active
`template`	The message that will be sent to your user in an SMS or a text-to-speech Call.
`type`	The encoding used for the template when the `action_type` is `sms`. Possible values are: `unicode` or `text` (default)
`version`	The template's version number. This number is generated automatically.
`welcome_message`	The ID of the media file played at the start of the call.