テンプレートの検証
Verify API が検証プロセス中に送信するメッセージは、テンプレートを使用して作成されます。デフォルトのテンプレートが用意されています。独自のテンプレートを作成して、Verify API がお客様に代わって送信する SMS または音声メッセージの内容をカスタマイズし、完全にブランド化されたエクスペリエンスをお客様に提供することができます。
デフォルトのテンプレートを使い続けたい場合は、これ以上の設定は必要ありませんので、このガイドは無視してかまいません。
デフォルトテンプレート
デフォルトでは、Verify APIは以下のテンプレートを使用する:
{
"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."
}
{
"action_type": "sms",
"lg": "en-us",
"template": "${brand} code: ${pin}. Valid for ${pin_expiry} minutes."
}
上記のテンプレートでは ${pin}, ${brand} そして ${pin_expiry} は テンプレート変数.
テンプレート変数
Verifyテンプレートでは、以下の変数を使用することができます:
${pin}ランダム認証コードのプレースホルダ${brand}会社名またはアプリケーション名${pin_expiry}認証コードの有効時間(秒単位
について ${pin} はVerify APIによってランダムに生成される。の値は ${brand} そして ${pin_expiry} への呼び出しで設定したパラメータである。 Verify リクエスト.
について <break time="1s" /> は 音声合成マークアップ言語 (SSML) タグを追加します。音声合成メッセージが再生される前に1秒のディレイが追加されます。
カスタムテンプレートの作成
カスタム・テンプレートを作成するには、まずJSON形式でテンプレートを定義し、次に 登録 それだ。
次の表は、カスタムテンプレートで使用できる設定の一覧です:
| パラメータ | 説明 | 必須 |
|---|---|---|
action_type | 可能な値は以下の通り: sms - テキストメッセージを送信する または voice - 音声合成メッセージを送信する | はい |
lg | を指定する。 ロケール 選択した言語、アクセント、性別で音声合成認証メッセージを配信するために使用されます。すべての Verify リクエスト カスタム・テンプレートには、同じ lg. 非標準のロケールを使用したい場合は、「カスタムロケール」の例に示すように、テンプレートに音声ファイルへのリンクを設定する必要があります。 これ. | はい |
template | SMSメッセージに表示される内容(SMSメッセージで action_type は smsの場合)、または音声合成通話でユーザーに話しかけられます。 action_type は voice).このコンテンツには以下が含まれる。 変数.の値を指定する。 template そして action_type は voice指定しない digit_n, welcome_message または bye_message. | いいえ |
type | に使用されるエンコーディング template の場合 action_type は sms.可能な値は以下の通り: unicode または text | いいえ |
digit_n | Vonageが音声合成で数字を読み上げる際に再生されるメディアファイルへのURL。もし digit_nを指定する必要があります。 welcome_message そして bye_message.Vonageはこの2つの間に認証コードを挿入する。 | いいえ |
welcome_message | 通話開始時に再生されるメディアファイルのURL。 | はい。 digit_n |
bye_message | 通話終了時に再生されるメディアファイルのURL。 | はい。 digit_n |
contact_email | Zendesk チケットの生成およびカスタムテンプレートの有効化に使用するメールアドレスを設定します。このパラメータを設定しない場合、Verify はマスター API キーに関連付けられたメールアドレスを使用します。 | いいえ |
カスタムテンプレート例
以下はテンプレートの例である:
{
"action_type": "voice",
"lg": "ja-jp",
"contact_email" : "xyz@example.com",
"template": "あなたの ${brand}コードは ${pin} です。 繰り返します。 あなたの ${brand}コードは ${pin} です。"
}
{
"action_type" : "sms",
"lg" : "ru-ru",
"type" : "unicode",
"contact_email" : "xyz@example.com",
"template" : "Ваш код подтверждения ${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"
}
カスタムテンプレートの登録
リクエスト
テンプレートを定義したら、Verify APIに登録する必要がある。これは https://api.nexmo.com/verify/templates エンドポイントに、テンプレートをペイロードとして渡します。
以下のコード例は、カスタム・テンプレートの登録方法を示しています:
<?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
対応を理解する
JSONレスポンスは次のようになる:
{
"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"
}
{
"account_id": "xxxxxxxx",
"action_type": "sms",
"lg": "en-gb",
"version": 2,
"status": "pending",
"template": "${pin} is your ${brand} verification code.",
"type": "text"
}
レスポンス・ヘッダは、以下のHTTPステータス・コードのいずれかを含む:
- [201] - カスタムテンプレートが作成されました。
- [400] - リクエストに不正なパラメータが含まれているか、テンプレートで指定したメディアをアップロードできませんでした。
- [401] - その
api_key/api_secretリクエストに使用したAccountが無効であるか、アカウントが無効になっています。 - [500] - 内部エラー。
レスポンス・ボディには以下のキーと値が含まれる:
| キー | 価値 |
|---|---|
account_id | あなたの api_key. |
action_type | 可能な値は以下の通り: sms - SMSテンプレート または voice - 音声テンプレートを使用 |
bye_message | 通話終了時に再生されるメディアファイルのID。 |
digit_n | 各桁に使用されているメディアファイルのID。 |
lg | テンプレート ロケール. |
status | システム内のテンプレートの現在のステータス。取り得る値は ACTIVE - 現在使用中、 PENDING - 承認とアクティベーション待ち または RETIRED - 活動休止 |
template | SMSまたは音声合成でユーザーに送信されるメッセージ。 |
type | のときにテンプレートに使われるエンコーディング。 action_type は sms.可能な値は以下の通り: unicode または text (デフォルト) |
version | テンプレートのバージョン番号。この番号は自動的に生成されます。 |
welcome_message | 通話開始時に再生されたメディアファイルのID。 |