テンプレートの作成
リクエスト 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
リクエストボディ
{
"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": 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
メール本文の例
<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"
}
送信パラメータの説明
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
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"
}
}
}
変数の差し込み優先順位
- 送信インターフェースの
template.paramsで渡された変数値を優先する; - 渡されなかった場合、テンプレートの
pre_param_mapの既定値を使用する; - どちらも設定されていない場合、プレースホルダーがメール内容にそのまま表示される。
よくある質問
Q: なぜ変数が置換されないのですか?
A: 変数名の表記と形式が正しいか({{variable_name}} が必要)を確認し、template.params で値が指定されているか、またはテンプレートに既定値が設定されているかを確認してください。
Q: メールの件名と送信者を動的に設定するには?
A: リクエストパラメータ template.params に subject、from_name、from_mail を渡すことで、テンプレートの既定の件名と送信者情報を動的に上書きできます。
エラーコード
| エラーコード | HTTP コード | 説明 |
|---|---|---|
| 1000 | 500 | 内部エラー |
| 2001 | 401 | 認証失敗。付与されたトークンが正しくない |
| 2002 | 401 | 認証失敗。トークンが期限切れまたは無効化されている |
| 2004 | 403 | この API を呼び出す権限がない |
| 3001 | 400 | リクエストパラメータの形式が不正。JSON の内容がパラメータ形式に準拠しているか確認してください |
| 3002 | 400 | リクエストパラメータが正しくない。リクエストパラメータが要件を満たしているか確認してください |
| 3003 | 400 | ビジネスレベルのパラメータエラー。返却された message フィールドの説明を確認してください |










