テンプレート

アカウントが送信に使うメールテンプレート、SMS ヘッダーと DLT テンプレート、WhatsApp 番号とテンプレートを管理します。読み取りにはチャネルの送信スコープまたは templates:manage が必要です。変更には templates:manage を持つ Owner または Admin キーが必要です。


メールテンプレート

アカウントのメールテンプレートは、API のメッセージと同じデフォルトワークスペースに属し、ダッシュボードでもそこに表示されます。API で作成したテンプレートは HTML で、{{name}} のプレースホルダーを送信時に埋め込みます。ダッシュボードのエディターでデザインしたテンプレートは、読み取り、送信への使用、削除はできますが、HTML とデザインの不整合を防ぐため置き換えられません。

メソッドパス機能
GET/external/v1/templates新しい順のテンプレート一覧。HTML は含みません
GET/external/v1/templates/{id}HTML と必要な変数を含む単一のテンプレート
POST/external/v1/templatesHTML からテンプレートを作成:201
PUT/external/v1/templates/{id}HTML から作成したテンプレートの名前、件名、HTML を置換
DELETE/external/v1/templates/{id}テンプレートを削除:204。以後は一覧に表示されず、送信にも使えません
  • 名前
    name
    タイプ
    string
    説明

    必須:テンプレート名。最大 255 文字です。Oblic の標準の名前検証も適用され、長さの条件だけでは不十分です。

  • 名前
    subject
    タイプ
    string
    説明

    送信時に件名を指定しない場合にこのテンプレートのメールで使う件名。独自のプレースホルダーを含められ、最大 1,023 文字です。省略または空白の件名は null として保存され、空白でない件名の前後の空白は除去されます。

  • 名前
    html
    タイプ
    string
    説明

    必須:HTML。指定どおりに保存され、最大 65,535 UTF-8 バイトです。送信時にプレースホルダーへ埋め込む変数値は HTML エスケープされますが、テンプレートの HTML 自体を無害化したりサンドボックス化したりするものではありません。

テンプレートの作成

curl -X POST https://api.oblic.app/external/v1/templates \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Order shipped",
    "subject": "Order {{order_id}} is on its way",
    "html": "<p>Hi {{first_name}}, your order {{order_id}} has shipped.</p>"
  }'

201 作成済み

{
  "status": "success",
  "data": {
    "id": "TEM000R7ZM4Q2VXH00",
    "name": "Order shipped",
    "subject": "Order {{order_id}} is on its way",
    "kind": "html",
    "variables": ["order_id", "first_name"],
    "html": "<p>Hi {{first_name}}, your order {{order_id}} has shipped.</p>",
    "createdAt": "2026-10-24T09:30:00Z",
    "updatedAt": "2026-10-24T09:30:00Z"
  },
  "errors": null
}
  • プレースホルダーは {{name}} です。名前には ASCII の英字と数字、_、.、-、名前の内部の空白のみを使え、最大 64 文字です。variables は件名と HTML のプレースホルダーを大文字小文字を区別せず列挙し、最初に現れた順序と表記を保持します。
  • kind は API で作成したテンプレートでは html、ダッシュボードのエディターで作成したものでは designed です。件名がない場合は送信時に指定してください。種類だけで判断せず、返された件名を確認します。
  • ダッシュボードのメンションである @unsubscribe や @organizationName は、キャンペーンと自動化のみが受信者ごとに埋め込みます。これらを含むテンプレートによる送信は拒否されます。
  • 一覧は cursor と limit でページ分割します。デフォルトは各ページ 25 件、範囲は 1 から 100 です。詳細はページネーションを参照してください。返されたカーソルは内部を解釈しない不透明な値として扱います。
拒否cd条件
400TEMPLATE_TOO_LARGEHTML が 65,535 バイトを超えている
404TEMPLATE_NOT_FOUNDその ID のテンプレートがアカウントにない
409TEMPLATE_DESIGNEDダッシュボードのエディターでデザインしたテンプレートの置換

SMS ヘッダーとテンプレート

SMS は DLT ヘッダーから送信され、Cunomial に設定された DLT エンティティのコンテンツテンプレートに一致する必要があります。両方を先に DLT プラットフォームへ登録し、ここには SMS 送信と照合するための情報を保存します。ここへの保存は DLT 登録の代わりにはなりません。SMS アカウントの応答の keepsRegistry と available は、設定された登録管理権限と利用可能性を示し、配信を保証するものではありません。

一覧には承認済みの登録テンプレートのみが表示されます。無効な承認済みテンプレートが表示されることもあります。送信には有効なテンプレートと、メッセージに記載された他の送信条件も必要です。

メソッドパス機能
GET/external/v1/sms/accountアカウントの制限、今月の送信実績、送信できるメッセージ種別
GET/external/v1/sms/sendersアカウント自身のヘッダー、[{"senderId": …, "isDefault": …}]
PUT/external/v1/sms/senders/{senderId}英字六文字または数字六桁のヘッダーを追加。{"isDefault": true} でデフォルトに設定
DELETE/external/v1/sms/senders/{senderId}どのテンプレートも使っていないヘッダーを削除:204
GET/external/v1/sms/templatesアカウント自身のテンプレートに続き、親アカウントが共有したテンプレート
POST/external/v1/sms/templatesテンプレートを追加:201
PUT/external/v1/sms/templates/{id}全項目を指定してテンプレートを変更
DELETE/external/v1/sms/templates/{id}テンプレートを削除:204
PUT/external/v1/sms/templates/{id}/sharing共有なし、すべて、または指定したサブアカウントに送信での使用を許可
  • 名前
    templateId
    タイプ
    string
    説明

    必須:テンプレートの DLT ID。数字で最大 32 桁です。

  • 名前
    senderId
    タイプ
    string
    説明

    必須:アカウントのヘッダーの一つ。販促用テンプレートは数字六桁、それ以外は英字六文字のヘッダーを使います。

  • 名前
    name
    タイプ
    string
    説明

    必須:任意の名前。最大 80 文字です。

  • 名前
    body
    タイプ
    string
    説明

    必須:DLT に登録したテキスト。最大 2,000 文字で、各変数は {#var#} と表記し、最大 30 個です。

  • 名前
    variableKeys
    タイプ
    string[]
    説明

    ["otp", "minutes"] など、各変数の名前を順番に指定します。省略または空の場合は 1 から n の位置名を使います。指定する場合、名前はそれぞれ一意で、ASCII の英字と数字または _ を使い、各 1 から 30 文字とし、名前の数を変数の数に一致させます。

  • 名前
    type
    タイプ
    string
    説明

    必須:DLT 種別。transactional、service_implicit、service_explicit、promotional のいずれかです。

  • 名前
    unicode
    タイプ
    boolean
    説明

    テキストが Unicode かどうか。デフォルトは false です。

  • 名前
    active
    タイプ
    boolean
    説明

    送信を許可するかどうか。デフォルトは true です。

テンプレートの追加

curl -X POST https://api.oblic.app/external/v1/sms/templates \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "templateId": "1107161234567890123",
    "senderId": "EXMPLE",
    "name": "Sign-in code",
    "body": "Your Example code is {#var#}. It is valid for {#var#} minutes.",
    "variableKeys": ["code", "minutes"],
    "type": "service_implicit"
  }'
  • Oblic が SMS 登録を行うアカウントのみが、ヘッダーとテンプレートを追加・変更できます。他のアカウントは 403 REGISTRY_NOT_ALLOWED で拒否され、共有されたテンプレートを使って送信します。
  • 共有には {"scope": "none" | "all" | "selected", "accounts": […]} を指定します。サブアカウントの externalId は最大 1,000 件で、selected に使います。指定する各アカウントは親アカウントに属する必要があります。選択リストが空なら、どのサブアカウントとも共有しません。
  • ヘッダーのデフォルト指定は各 PUT で設定されます。"isDefault": true がなければ、そのヘッダーはデフォルトではなくなります。一つをデフォルトにすると、以前のデフォルトヘッダーの指定が解除されます。
拒否cd条件
400INVALID_TEMPLATEヘッダーが種別に合わない、変数が 30 個を超える、または variableKeys が各変数を一度ずつ指定していない
403REGISTRY_NOT_ALLOWEDアカウントが自身の SMS 登録を行わない
404TEMPLATE_NOT_FOUND, SENDER_NOT_FOUND, ACCOUNT_NOT_FOUND該当するテンプレート、ヘッダー、サブアカウントがない
409TEMPLATE_EXISTSその DLT ID のテンプレートが登録済み
409SENDER_IN_USEテンプレートが使用中のヘッダーの削除
422SENDER_NOT_ALLOWEDヘッダーがアカウントに属していない
422MESSAGE_TYPE_NOT_ENABLEDテンプレートの種別が Oblic の送信対象外。アカウントの messageTypes により、デフォルトは service_implicit のみ

WhatsApp 番号とテンプレート

WhatsApp メッセージは、アカウントに接続された WhatsApp Business 番号から、Meta 承認済みテンプレートで送信します。

メソッドパス機能
POST/external/v1/whatsapp/connection番号を接続、または接続済み番号を置換
GET/external/v1/whatsapp/connection接続済み番号。ない場合は 404 WHATSAPP_NOT_CONNECTED
DELETE/external/v1/whatsapp/connection接続を解除:204
GET/external/v1/whatsapp/templatesテンプレートと、それぞれの Meta 審査結果
POST/external/v1/whatsapp/templatesMeta にテンプレートを審査申請:201
GET/external/v1/whatsapp/recipients/{number}アカウントが現在その番号へ送信できる内容

接続には、Oblic の Meta アプリで実行した Embedded Signup の結果を使います。code、phoneNumberId、wabaId、任意の businessId、番号登録に使う六桁の pin が必要です。すべての接続手順を確認すると応答の status は INTEGRATED になり、途中で停止した接続は PENDING のままです。有効な登録情報で再試行してください。使用済みまたは期限切れのコードが再度使える保証はありません。Meta が手順を拒否すると 502 と該当コード(例:WHATSAPP_REGISTER_REFUSED)を返し、生の応答本文は返しません。

  • 名前
    name
    タイプ
    string
    説明

    必須:ASCII の小文字、数字、_。例は order_shipped です。Oblic がアカウントと言語を含めて拡張した名前は最大 100 文字で、超過は Meta 呼び出し前に拒否されます。送信には返された name を使い、短い入力名が Meta の保存名だと決めつけないでください。

  • 名前
    language
    タイプ
    string
    説明

    テンプレートの言語:ASCII 小文字二文字に、必要に応じて _ と ASCII 大文字二文字を追加します。例は en、hi、en_US で、省略時は en です。同じ名前でも言語ごとにテンプレートを作成できますが、同じ名前と言語の重複は競合になります。

  • 名前
    category
    タイプ
    string
    説明

    必須:MARKETING、UTILITY、AUTHENTICATION のいずれか。

  • 名前
    components
    タイプ
    object[]
    説明

    必須:Meta 形式のヘッダー、本文、フッター、ボタンと、それらの変数の例。

テンプレートの審査申請

curl -X POST https://api.oblic.app/external/v1/whatsapp/templates \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "order_shipped",
    "language": "en",
    "category": "UTILITY",
    "components": [
      {
        "type": "BODY",
        "text": "Hi {{1}}, your order {{2}} has shipped.",
        "example": { "body_text": [["Asha", "1042"]] }
      }
    ]
  }'
  • テンプレートの status は、保存された Meta 審査状態です。例は PENDING、APPROVED、REJECTED で、rejectionReason がない場合もあります。201 は申請済みを意味し、承認済みではありません。送信できるのは APPROVED テンプレートのみで、審査完了期限は保証されません。
  • 受信者の応答には number、optedOut、その日時と方法(optedOutAt、optOutSource)、lastInboundAt、sessionOpenUntil が含まれます。ウィンドウは本人の最後の受信メッセージから 24 時間です。optedOut はマーケティングに関するもので、すべてのメッセージが対象ではありません。受信履歴がない場合、lastInboundAt と sessionOpenUntil は null です。セッションの時刻だけで送信の受け付けが保証されるわけではなく、他の送信条件も適用されます。
拒否cd条件
409TEMPLATE_EXISTSその名前と言語のテンプレートがアカウントにある
422WHATSAPP_NOT_CONNECTED番号を接続せずにテンプレートを申請
422TEMPLATE_NAME_TOO_LONG名前が Meta の長さ制限を超えている
422TEMPLATE_REFUSEDMeta がテンプレートを拒否。Meta の生の応答ではなく、汎用のローカライズ済み拒否メッセージを返す
422INVALID_NUMBER受信者番号が国際形式ではない
502WHATSAPP_CODE_REFUSED, WHATSAPP_SUBSCRIBE_REFUSED, WHATSAPP_REGISTER_REFUSEDMeta が番号の接続手順を拒否
503WHATSAPP_UNAVAILABLE接続手順中に Meta に到達できなかった
このページは役に立ちましたか?