テンプレート管理

Verify API によるテンプレート管理では、デフォルトの Vonage テンプレートを使用するのではなく、ユーザーに OTP を配信するために送信されるメッセージをカスタマイズできます。カスタム・テンプレートは、SMS および音声に設定できます。 対応ロケール.

テンプレート構造

カスタムテンプレートは2つの部分に分かれている：

• について template - このテンプレートには一意な名前とIDがあり、デフォルト・テンプレートかどうかも含まれます。テンプレートは作成時に常にデフォルトに設定され、後で変更することができます。

• template_fragments - テンプレートは多くのフラグメントを持つことができる。 locale そして channelこれにより、1つのチャンネルに複数の言語でカスタム・テンプレートを作成することができます。テンプレートには、ID、テンプレートメッセージ、作成日と更新日のタイムスタンプが含まれます。

フラグメントを作成するとき、メッセージテキスト内で4つの静的変数を使うことができます。メッセージに含まれなければならない唯一の変数はコードで、これはテキスト中では ${code}.

テンプレートの作成

テンプレートを作成するには、

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

応答では template_idまた、テンプレートとそのフラグメントが作成されたら、それを表示するために使用できるリンクもあります：

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

で示されるように、最初に作成したカスタムテンプレートが自動的にデフォルトテンプレートとして設定されます。 is_default = true.これを変更するには テンプレートの更新.

次に、カスタムメッセージを使用したいロケールとチャンネルごとにフラグメントを作成する必要があります。

フラグメントの作成

フラグメントを作成するには、

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

このリクエストの本文に

• channel このフラグメントのチャネルを指定します。 sms または voice.
• locale はメッセージが書かれた言語のロケール・コードである。例えば en-gb は英語（英国）、そして de-de はドイツ語である。
• text は送信したいメッセージです。この マスト を含む。 ${code} 変数を含めることができます。その他、オプションで静的変数を含めることができる：
  • ${brand} - はVerifyリクエストの "brand "パラメータ値に置き換えられる。
  • ${time-limit} - コードが期限切れとみなされるまでの時間（Numbers）に置き換えられます。
  • ${time-limit-unit} - は、ピンコード有効期限の時間単位（秒、分）に置き換えられます(time-limit).

このリクエストは、英国の誰かに送るSMSのテンプレートメッセージを作成します。例えば、フランスの誰かに送るためにこのメッセージのバージョンを作成するには、別の

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

Verifyはどのように使用するテンプレートを選ぶのか？

リクエストに使用するテンプレートを決定するために、Verify APIは以下のステップに従う：

• Verifyリクエストが送信されると、APIはリクエストで指定されたロケールを使用するか、リクエストの送信先のロケールを検出する。
  • ロケールを検出するために、Verifyは提供された電話番号を使って、その人がどこにいるかを判断する。例えば 447700900000 にマップされます。 en-gb は英国の番号である。 847700900000 にマップされます。 fr-fr これはフランスのナンバーである。
  • 特定の言語でメッセージを送信する必要がある場合は locale パラメータをリクエストに追加します。これはカナダのように複数の公用語がある場合に便利です。

使用するロケールを決定すると、Verifyはそのロケールに一致するテンプレートを探します：

• もし template_id をリクエストに含めると、まずそのテンプレートを見て、そのロケールとチャネルのカスタムテンプレートが作成されているかどうかを確認します。もしあれば、そのテンプレートを使ってOTPメッセージを送信します。
• それが存在しない場合、またはあなたが提供しなかった場合 template_id をリクエストに含めると、Verify はそのロケール用のデフォルトのテンプレートを使おうとします。
  • カスタム・テンプレートを作成した場合、次のようなテンプレートを使用しようとします。 is_default をtrueに設定する。
  • そうでない場合は、Vonageのデフォルト・テンプレートを使用しようとします。
• そのロケールに対応するテンプレートが見つからない場合、あるいはそのチャンネルでサポートされていないロケールを使用している場合、デフォルトは次のようになります。 en_US.

完全な流れを以下に示す：

その他のテンプレート操作

すべてのテンプレート操作の詳細は API仕様の検証リクエストとレスポンスの例を含む。また、以下に要約する：

テンプレートの表示

このエンドポイントに

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

または、テンプレートIDを指定して同じエンドポイントに

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

テンプレートの更新

を更新することができます。 name を変更することで、テンプレートがデフォルトのテンプレートであるかどうかを設定できます。 is_default パラメータを使用してください。そのためには PATCH リクエストをこのエンドポイントに置き換える。 :template_id を更新するテンプレートのIDに置き換えてください：

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
}

テンプレートの削除

このエンドポイントに

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

その他のテンプレート・フラグメントの操作

すべてのテンプレート操作の詳細は API仕様の検証しかし、以下に要約する：

テンプレートフラグメントの表示

このエンドポイントに

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

必ず交換してください。 :template_id には、フラグメントを表示したいテンプレートのIDを指定します。

特定のテンプレートを表示するには、テンプレートIDとテンプレート・フラグメントIDを指定して、同じエンドポイントに

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

テンプレート・フラグメントの更新

テンプレート・フラグメントを使って送信するメッセージは text パラメータを使用します。ロケールとチャンネルは更新できない。

を送信してください。 PATCH リクエストをこのエンドポイントに置き換える。 :template_id そして :template_fragment_id をテンプレートIDとテンプレート・フラグメント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}"
}

テンプレート断片の削除

このエンドポイントに

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

トラブルシューティング

カスタムテンプレートを使用しようとしたときに遭遇する可能性のある一般的なエラーをいくつか紹介します：

• アカウントが有効になっていない:テンプレートを読むことはすべてのユーザーが可能ですが、カスタムテンプレートの作成はアカウントで有効にする必要があります。この機能を有効にするには、アカウントマネージャーに連絡するか、サポートにご相談ください。
• テンプレートまたはフラグメントが存在する:各テンプレートは一意な名前を持たなければならず、そのテンプレート上の各フラグメントは、ロケールとチャンネルを組み合わせた一意なエントリでなければならない。
• フラグメントを含むテンプレートの削除を試みる:既存のフラグメントがある場合、テンプレートを削除することはできません。テンプレートを削除するには HALフィールド テンプレート自身を削除する前に、削除する既存のフラグメントのIDをトラバースするために、get templateレスポンスのディスカバリーに使用します。
• 使用しない ${code} 本文中:フラグメントを作成するときは、テキスト内にコードを含める必要があります。
• テンプレートの最大数:それ以上のテンプレートを生成しようとするとエラーになります。