テンプレートの作成

リクエスト URL

POST https://otp.api.engagelab.cc/v1/template-configs

認証

API 認証の方法については 認証 を参照してください。

リクエスト

リクエストパラメータ

リクエストオブジェクトは JSON 形式で表現されるため、リクエストヘッダーには Content-Type: application/json を含める必要があります。

パラメータ 必須/任意 説明
template_id String 必須 カスタムテンプレート ID。一意である必要があり、最大 128 文字
description String 任意 テンプレートの説明。最大 255 文字
send_channel_strategy String 必須 テンプレート戦略。単一チャネルの値は whatsapp/sms/email/voice、複数チャネルは | で区切り、順にフォールバックします。email は他のチャネルと組み合わせできません
brand_name String 任意 ブランド表示。一部のテンプレートスタイルにブランド署名がある場合にブランド署名変数を置き換えます。長さは 2〜10 文字
verify_code_config Object 条件付き必須 検証コード設定。テンプレートに検証コード種別を含む場合は必須
verify_code_config.verify_code_type Integer 必須 検証コード種別。値の範囲は [1,7]。1 数字/2 小文字/4 大文字。組み合わせ可能(例: 3 は数字 + 小文字を意味する)
verify_code_config.verify_code_len Integer 必須 検証コードの長さ。値の範囲は [4,10]
verify_code_config.verify_code_ttl Integer 必須 検証コードの有効期間(分)。値の範囲は [1,10]。戦略に whatsapp を含む場合は 1、5、10 のみ指定可能
whatsapp_config Object 条件付き必須 whatsapp 戦略の設定。配信戦略に whatsapp を含む場合は必須
whatsapp_config.template_type Integer 必須 whatsapp テンプレート種別。現在はデフォルトテンプレートのみ対応し、固定値 1
whatsapp_config.template_default_config Object 条件付き必須 whatsapp デフォルトテンプレート設定。whatsapp テンプレート種別がデフォルトテンプレートの場合は必須
sms_config Object 条件付き必須 sms 戦略の設定。配信戦略に sms を含む場合は必須
sms_config.template_type Integer 必須 sms テンプレート種別。1-デフォルトテンプレート/2-カスタムテンプレート
sms_config.template_default_config Object 条件付き必須 sms デフォルトテンプレート設定。sms テンプレート種別がデフォルトテンプレートの場合は必須
sms_config.template_custom_config Object 条件付き必須 sms カスタムテンプレート設定。sms テンプレート種別がカスタムテンプレートの場合は必須
sms_config.template_custom_config.custom_sub_type String 必須 カスタムテンプレート種別。authentication/marketing/utility
sms_config.template_custom_config.custom_content String 必須 カスタムテンプレートの内容。種別が authentication の場合は {{code}} 変数を含める必要がある
sms_config.template_custom_config.custom_country_codes String 任意 対象の国/地域コード。カンマ区切り。テンプレート審査時の参考に使用
voice_config Object 条件付き必須 voice 戦略の設定。配信戦略に voice を含む場合は必須
voice_config.template_type Integer 必須 voice テンプレート種別。現在はデフォルトテンプレートのみ対応し、固定値 1
voice_config.template_default_config Object 条件付き必須 voice デフォルトテンプレート設定。voice テンプレート種別がデフォルトテンプレートの場合は必須
email_config Object 条件付き必須 email 戦略の設定。配信戦略に email を含む場合は必須
email_config.template_name String 必須 email テンプレート名
email_config.template_custom_configs Array 条件付き必須 email カスタムテンプレート設定。email テンプレート種別がカスタムテンプレートの場合は必須。多言語設定に対応
email_config.template_custom_configs.language String 必須 言語。デフォルトは default。メッセージ配信時に language パラメータに応じて異なるテンプレート内容をマッチできる
email_config.template_custom_configs.pre_from_name String 任意 既定の送信者名
email_config.template_custom_configs.pre_from_mail String 必須 既定の送信者メールアドレス
email_config.template_custom_configs.pre_subject String 必須 既定のメール件名
email_config.template_custom_configs.template_content String 必須 メール本文。html に対応。変数は {{}} で囲む必要がある
email_config.template_custom_configs.pre_param_map Object 任意 メール本文中の変数の既定値。キーと値のペアで宣言し、value は文字列である必要がある
pwa_config Object 任意 pwa 関連の設定。現在は未使用
pwa_config.pwa_platform String 任意 使用する pwa プラットフォーム。具体的な値はテクニカルサポートにお問い合わせください
pwa_config.pwa_code String 任意 使用する pwa プラットフォーム内の code

リクエスト例

リクエストヘッダー

POST /v1/template-configs HTTP/1.1 Content-Type: application/json Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0
              
              POST /v1/template-configs  HTTP/1.1
Content-Type: application/json
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0

            
このコードブロックはフローティングウィンドウ内に表示されます

リクエストボディ

{ "template_id": "test-template-1", // カスタムテンプレート id。アプリケーション内で一意 "description": "Test template 1", // テンプレートの説明 "send_channel_strategy": "whatsapp|sms",// テンプレート配信戦略。whatsapp/sms/voice/email に対応。組み合わせ戦略は | 文字で失敗時のフォールバックを表す "brand_name": "Brand Name", // ブランド名。一部の国/地域でテンプレート内容の署名に使用(例: 一部の国では SMS チャネルで登録済み署名が必要) "verify_code_config": { // 検証コード設定。自動生成される検証コードの設定に使用。テンプレートに検証コード種別を含む場合は必須 "verify_code_type": 1, // 検証コード種別。値の範囲は [1,7] "verify_code_len": 6, // 検証コードの長さ。値の範囲は [4,10] "verify_code_ttl": 1 // 検証コードの有効期間。値の範囲は [1,10]。戦略に whatsapp を含む場合、値は 1、5、10 のみ指定可能 }, "whatsapp_config": { // whatsapp 戦略の設定。配信戦略に whatsapp を含む場合に有効 "template_type": 1, // whatsapp テンプレート種別。現在はデフォルトテンプレートのみ対応し、固定値は 1 "template_default_config": { // whatsapp デフォルトテンプレート設定。デフォルトテンプレート種別の場合に有効 "contain_security": false, // セキュリティ注意を追加するかどうか "contain_expire": false // 有効期限の内容を追加するかどうか } }, "sms_config": { // sms 戦略の設定。配信戦略に sms を含む場合に有効 "template_type": 2, // sms テンプレート種別。値: 1-デフォルトテンプレート/2-カスタムテンプレート "template_default_config": { // sms デフォルトテンプレート設定。デフォルトテンプレート種別の場合に有効 "contain_security": false, // セキュリティ注意を追加するかどうか "contain_expire": false // 有効期限の内容を追加するかどうか }, "template_custom_config": { // sms カスタムテンプレート設定。sms テンプレート種別がカスタムテンプレートの場合に有効 "custom_sub_type": "authentication", // カスタムテンプレート種別。値: authentication/marketing/utility "custom_content": "xxx", // カスタムテンプレートの内容。サブ種別が authentication の場合は {{code}} 変数を含める必要がある "custom_country_codes": "HK,PH" // カスタムテンプレートの対象国/地域。テンプレート審査時の参考に使用。実際の状況に合わせて入力してください。そうでない場合、実際の配信に影響する可能性があります } }, "voice_config": { // voice 戦略の設定。配信戦略に voice を含む場合に有効 "template_type": 1, // voice テンプレート種別。現在はデフォルトテンプレートのみ対応し、固定値は 1 "template_default_config": { // voice デフォルトテンプレート設定。デフォルトテンプレート種別の場合に有効 "contain_security": false, // セキュリティ注意を追加するかどうか "contain_expire": false // 有効期限の内容を追加するかどうか } }, "email_config": { // email 戦略の設定。配信戦略に email を含む場合に有効 "template_name": "email template name", // email テンプレート名 "template_custom_configs": [{ // email カスタムテンプレート設定。オブジェクト配列であることに注意。主に language で複数言語を設定するために使用 "language": "default", // 言語。デフォルトは default。メッセージ配信時に language パラメータに応じて異なるテンプレート内容をマッチできる "pre_from_name": "test", // 既定の送信者名 "pre_from_mail": "test@test.com",// 既定の送信者メールアドレス "pre_subject": "test", // 既定のメール件名 "template_content": "Preset email template content, required, custom variables like {{self}}, verification code is {{code}}", // メール本文。html に対応。変数は二重波括弧 {{}} で囲む必要がある "pre_param_map": { // メール本文中の変数の既定値。つまり配信時に変数値を指定しない場合、以下の既定値で変数を置き換える。キーと値のペアで宣言し、value は文字列である必要がある "self": "Here is the preset value for the self variable" } }] }, "pwa_config": { // pwa 関連の設定。現在は未使用 "pwa_platform": "xx", // 使用する pwa プラットフォーム。具体的な値はテクニカルサポートにお問い合わせください "pwa_code": "xx" // 使用する pwa プラットフォーム内の code } }
              
              {
    "template_id": "test-template-1",       // カスタムテンプレート id。アプリケーション内で一意
    "description": "Test template 1",       // テンプレートの説明
    "send_channel_strategy": "whatsapp|sms",// テンプレート配信戦略。whatsapp/sms/voice/email に対応。組み合わせ戦略は | 文字で失敗時のフォールバックを表す
    "brand_name": "Brand Name",             // ブランド名。一部の国/地域でテンプレート内容の署名に使用(例: 一部の国では SMS チャネルで登録済み署名が必要)
    "verify_code_config": {                 // 検証コード設定。自動生成される検証コードの設定に使用。テンプレートに検証コード種別を含む場合は必須
        "verify_code_type": 1,              // 検証コード種別。値の範囲は [1,7]
        "verify_code_len": 6,               // 検証コードの長さ。値の範囲は [4,10]
        "verify_code_ttl": 1                // 検証コードの有効期間。値の範囲は [1,10]。戦略に whatsapp を含む場合、値は 1、5、10 のみ指定可能
    },
    "whatsapp_config": {                    // whatsapp 戦略の設定。配信戦略に whatsapp を含む場合に有効
        "template_type": 1,                 // whatsapp テンプレート種別。現在はデフォルトテンプレートのみ対応し、固定値は 1
        "template_default_config": {        // whatsapp デフォルトテンプレート設定。デフォルトテンプレート種別の場合に有効
            "contain_security": false,      // セキュリティ注意を追加するかどうか
            "contain_expire": false         // 有効期限の内容を追加するかどうか
        }
    },
    "sms_config": {                         // sms 戦略の設定。配信戦略に sms を含む場合に有効
        "template_type": 2,                 // sms テンプレート種別。値: 1-デフォルトテンプレート/2-カスタムテンプレート
        "template_default_config": {        // sms デフォルトテンプレート設定。デフォルトテンプレート種別の場合に有効
            "contain_security": false,      // セキュリティ注意を追加するかどうか
            "contain_expire": false         // 有効期限の内容を追加するかどうか
        },
        "template_custom_config": {         // sms カスタムテンプレート設定。sms テンプレート種別がカスタムテンプレートの場合に有効
            "custom_sub_type": "authentication", // カスタムテンプレート種別。値: authentication/marketing/utility
            "custom_content": "xxx",        // カスタムテンプレートの内容。サブ種別が authentication の場合は {{code}} 変数を含める必要がある
            "custom_country_codes": "HK,PH" // カスタムテンプレートの対象国/地域。テンプレート審査時の参考に使用。実際の状況に合わせて入力してください。そうでない場合、実際の配信に影響する可能性があります
        }
    },
    "voice_config": {                       // voice 戦略の設定。配信戦略に voice を含む場合に有効
        "template_type": 1,                 // voice テンプレート種別。現在はデフォルトテンプレートのみ対応し、固定値は 1
        "template_default_config": {        // voice デフォルトテンプレート設定。デフォルトテンプレート種別の場合に有効
            "contain_security": false,      // セキュリティ注意を追加するかどうか
            "contain_expire": false         // 有効期限の内容を追加するかどうか
        }
    },
    "email_config": {                       // email 戦略の設定。配信戦略に email を含む場合に有効
        "template_name": "email template name", // email テンプレート名
        "template_custom_configs": [{       // email カスタムテンプレート設定。オブジェクト配列であることに注意。主に language で複数言語を設定するために使用
            "language": "default",          // 言語。デフォルトは default。メッセージ配信時に language パラメータに応じて異なるテンプレート内容をマッチできる
            "pre_from_name": "test",        // 既定の送信者名
            "pre_from_mail": "test@test.com",// 既定の送信者メールアドレス
            "pre_subject": "test",          // 既定のメール件名
            "template_content": "Preset email template content, required, custom variables like {{self}}, verification code is {{code}}", // メール本文。html に対応。変数は二重波括弧 {{}} で囲む必要がある
            "pre_param_map": {              // メール本文中の変数の既定値。つまり配信時に変数値を指定しない場合、以下の既定値で変数を置き換える。キーと値のペアで宣言し、value は文字列である必要がある
                "self": "Here is the preset value for the self variable"
            }
        }]
    },
    "pwa_config": {                         // pwa 関連の設定。現在は未使用
        "pwa_platform": "xx",               // 使用する pwa プラットフォーム。具体的な値はテクニカルサポートにお問い合わせください
        "pwa_code": "xx"                    // 使用する pwa プラットフォーム内の code
    }
}

            
このコードブロックはフローティングウィンドウ内に表示されます

レスポンス

レスポンスパラメータ

フィールド 必須/任意 説明
code Integer 必須 エラーコード。0 は成功、それ以外は失敗を意味する
message String 必須 レスポンスメッセージ

レスポンス例

成功レスポンス

{ "code": 0, "message": "success" }
              
              {
    "code": 0,
    "message": "success"
}

            
このコードブロックはフローティングウィンドウ内に表示されます

失敗レスポンス

{ "code": 3003, "message": "not contains any channel config" }
              
              {
    "code": 3003,
    "message": "not contains any channel config"
}

            
このコードブロックはフローティングウィンドウ内に表示されます

Email テンプレート変数の高度な使い方

送信戦略で Email チャネルを有効にすると、メールの件名と本文を高度にカスタマイズできます。変数プレースホルダー {{variable_name}} を使うことで、検証コードやブランド情報などを自動的に差し込み、柔軟でパーソナライズされたメール体験を実現できます。

変数の種類と使い方

変数は Email テンプレートの本文(template_content)と件名(pre_subject)の両方に {{variable_name}} の形式で埋め込めます。

送信 API では template.params フィールドを通じて動的に渡すか、テンプレート作成段階で既定値を設定します。

対応している変数

以下の変数は Email チャネルのみに適用されます。

変数名 説明 入力方法
{{logo_url}} カスタム変数 ブランドロゴ画像の URL 送信時に template.params で渡す
{{title}} カスタム変数 メール本文のタイトルテキスト 送信時に template.params で渡す
{{support_email}} カスタム変数 カスタマーサポートのメールアドレス 送信時に template.params で渡す
{{subject}} カスタム変数 メール件名を動的に上書き 送信時に template.params で渡す
{{from_name}} カスタム変数 送信者名を動的に上書き 送信時に template.params で渡す
{{from_mail}} カスタム変数 送信者メールアドレスを動的に上書き 送信時に template.params で渡す

注意: 特殊変数 {{subject}}{{from_name}}{{from_mail}} は本文 HTML には挿入されず、メールのメタデータフィールドを直接上書きします。

メール件名の例

{{brand_name}} Verification Code
              
              {{brand_name}} Verification Code

            
このコードブロックはフローティングウィンドウ内に表示されます

メール本文の例

<img src="{{logo_url}}" /> <strong>{{title}}</strong> <p>Your verification code is <strong>{{code}}</strong>, please complete verification within {{ttl}} minutes.</p> <p>If you have any questions, please contact <a href="mailto:{{support_email}}">{{support_email}}</a></p>
              
              <img src="{{logo_url}}" />
<strong>{{title}}</strong>
<p>Your verification code is <strong>{{code}}</strong>, please complete verification within {{ttl}} minutes.</p>
<p>If you have any questions, please contact <a href="mailto:{{support_email}}">{{support_email}}</a></p>

            
このコードブロックはフローティングウィンドウ内に表示されます

テンプレートの既定値設定

テンプレート作成時に、pre_param_map フィールドでカスタム変数の既定値を設定できます。メール送信時に変数が渡されなかった場合、既定値が自動的に使用されます。

"pre_param_map": { "logo_url": "https://example.com/logo.png", "title": "Your Verification Code", "support_email": "support@example.com" }
              
              "pre_param_map": {
  "logo_url": "https://example.com/logo.png",
  "title": "Your Verification Code",
  "support_email": "support@example.com"
}

            
このコードブロックはフローティングウィンドウ内に表示されます

送信パラメータの説明

フィールド 必須 説明
to string はい 宛先メールアドレス
template.id string はい Email テンプレート ID
template.language string いいえ 言語コード。デフォルトは default
template.params object いいえ テンプレート変数の割り当て({{}} なし)

リクエスト例:

{ "to": "user@example.com", "template": { "id": "my_email_template", "language": "default", "params": { "logo_url": "https://example.com/logo.png", "title": "Your Verification Code", "support_email": "support@example.com" } } }
              
              {
  "to": "user@example.com",
  "template": {
    "id": "my_email_template",
    "language": "default",
    "params": {
      "logo_url": "https://example.com/logo.png",
      "title": "Your Verification Code",
      "support_email": "support@example.com"
    }
  }
}

            
このコードブロックはフローティングウィンドウ内に表示されます

変数の差し込み優先順位

  1. 送信インターフェースの template.params で渡された変数値を優先する;
  2. 渡されなかった場合、テンプレートの pre_param_map の既定値を使用する;
  3. どちらも設定されていない場合、プレースホルダーがメール内容にそのまま表示される。

よくある質問

Q: なぜ変数が置換されないのですか?
A: 変数名の表記と形式が正しいか({{variable_name}} が必要)を確認し、template.params で値が指定されているか、またはテンプレートに既定値が設定されているかを確認してください。

Q: メールの件名と送信者を動的に設定するには?
A: リクエストパラメータ template.paramssubjectfrom_namefrom_mail を渡すことで、テンプレートの既定の件名と送信者情報を動的に上書きできます。

エラーコード

エラーコード HTTP コード 説明
1000 500 内部エラー
2001 401 認証失敗。付与されたトークンが正しくない
2002 401 認証失敗。トークンが期限切れまたは無効化されている
2004 403 この API を呼び出す権限がない
3001 400 リクエストパラメータの形式が不正。JSON の内容がパラメータ形式に準拠しているか確認してください
3002 400 リクエストパラメータが正しくない。リクエストパラメータが要件を満たしているか確認してください
3003 400 ビジネスレベルのパラメータエラー。返却された message フィールドの説明を確認してください
Icon Solid Transparent White Qiyu
お問い合わせ