テンプレート
アカウントが送信に使うメールテンプレート、SMS ヘッダーと DLT テンプレート、WhatsApp 番号とテンプレートを管理します。読み取りにはチャネルの送信スコープまたは templates:manage が必要です。変更には templates:manage を持つ Owner または Admin キーが必要です。
これらの /external/v1 ルートは API キーを使います。OAuth アクセストークンは API v2 を使います。例があるだけでは、そのバージョンがデプロイ環境で設定済みとは限りません。
メールテンプレート
アカウントのメールテンプレートは、API のメッセージと同じデフォルトワークスペースに属し、ダッシュボードでもそこに表示されます。API で作成したテンプレートは HTML で、{{name}} のプレースホルダーを送信時に埋め込みます。ダッシュボードのエディターでデザインしたテンプレートは、読み取り、送信への使用、削除はできますが、HTML とデザインの不整合を防ぐため置き換えられません。
| メソッド | パス | 機能 |
|---|---|---|
GET | /external/v1/templates | 新しい順のテンプレート一覧。HTML は含みません |
GET | /external/v1/templates/{id} | HTML と必要な変数を含む単一のテンプレート |
POST | /external/v1/templates | HTML からテンプレートを作成: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 | 条件 |
|---|---|---|
| 400 | TEMPLATE_TOO_LARGE | HTML が 65,535 バイトを超えている |
| 404 | TEMPLATE_NOT_FOUND | その ID のテンプレートがアカウントにない |
| 409 | TEMPLATE_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 | 条件 |
|---|---|---|
| 400 | INVALID_TEMPLATE | ヘッダーが種別に合わない、変数が 30 個を超える、または variableKeys が各変数を一度ずつ指定していない |
| 403 | REGISTRY_NOT_ALLOWED | アカウントが自身の SMS 登録を行わない |
| 404 | TEMPLATE_NOT_FOUND, SENDER_NOT_FOUND, ACCOUNT_NOT_FOUND | 該当するテンプレート、ヘッダー、サブアカウントがない |
| 409 | TEMPLATE_EXISTS | その DLT ID のテンプレートが登録済み |
| 409 | SENDER_IN_USE | テンプレートが使用中のヘッダーの削除 |
| 422 | SENDER_NOT_ALLOWED | ヘッダーがアカウントに属していない |
| 422 | MESSAGE_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/templates | Meta にテンプレートを審査申請: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 | 条件 |
|---|---|---|
| 409 | TEMPLATE_EXISTS | その名前と言語のテンプレートがアカウントにある |
| 422 | WHATSAPP_NOT_CONNECTED | 番号を接続せずにテンプレートを申請 |
| 422 | TEMPLATE_NAME_TOO_LONG | 名前が Meta の長さ制限を超えている |
| 422 | TEMPLATE_REFUSED | Meta がテンプレートを拒否。Meta の生の応答ではなく、汎用のローカライズ済み拒否メッセージを返す |
| 422 | INVALID_NUMBER | 受信者番号が国際形式ではない |
| 502 | WHATSAPP_CODE_REFUSED, WHATSAPP_SUBSCRIBE_REFUSED, WHATSAPP_REGISTER_REFUSED | Meta が番号の接続手順を拒否 |
| 503 | WHATSAPP_UNAVAILABLE | 接続手順中に Meta に到達できなかった |