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:

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 Nexmo 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. Nexmo 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" : "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} です。"
}
{
  "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"
}

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

#Create the custom template
payload='{
  "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:

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.