テンプレートの検証

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

上記のテンプレートでは ${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_typesmsの場合)、または音声合成通話でユーザーに話しかけられます。 action_typevoice).このコンテンツには以下が含まれる。 変数.
の値を指定する。 template そして action_typevoice指定しない digit_n, welcome_message または bye_message.
いいえ
type に使用されるエンコーディング template の場合 action_typesms.可能な値は以下の通り: 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} です。"
}

カスタムテンプレートの登録

リクエスト

テンプレートを定義したら、Verify APIに登録する必要がある。これは https://api.nexmo.com/verify/templates エンドポイントに、テンプレートをペイロードとして渡します。

以下のコード例は、カスタム・テンプレートの登録方法を示しています:

#!/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"

対応を理解する

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

レスポンス・ヘッダは、以下の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_typesms.可能な値は以下の通り: unicode または text (デフォルト)
version テンプレートのバージョン番号。この番号は自動的に生成されます。
welcome_message 通話開始時に再生されたメディアファイルのID。