waba-template-author

WhatsApp テンプレート作成者

このスキルを使って、メッセージの意図を POST /v3/templates 用の有効な本文に変換し、WhatsApp ポリシー上のリスクを確認して、その後のライフサイクルを説明します。Sent のテンプレートリクエストは、Meta の Cloud API の components[] 形式ではありません。

情報源の優先順位

公式情報源の内容が異なる場合：

1. パス、リクエストフィールド、レスポンス形式には、稼働中の Sent v3 OpenAPI を使用します。
2. ライフサイクルとポリシーの解釈には、最も具体的で最新の Sent ガイドを使用します。
3. 不明なプロバイダーの値は、クローズドな列挙型に無理に当てはめず、そのまま保持します。

正規の参照資料は、Sent のテンプレート定義ガイド、v3 OpenAPI、Webhook イベントのリファレンスです。スナップショット時代の v2 の例は使用しないでください。

作成ワークフロー

1. 意図とカテゴリを確定する

ビジネスイベント、受信者が期待する内容、要求するアクション、言語、チャネルごとのオーバーライド、現実的なサンプル値を確認します。次から選択します。

• UTILITY：特定の非プロモーション取引、アカウント、またはサービスに関するイベント。
• MARKETING：プロモーション、オファー、再エンゲージメント、製品の紹介、またはプロモーションを含むコンテンツ。
• AUTHENTICATION：ワンタイム認証コードと、サポートされている認証フロー。

コンテンツにユーティリティとプロモーションが混在する場合は、マーケティングに分類するか、分割してください。references/waba-template-categories.md を参照してください。

2. Sent の作成リクエストを作成する

POST /v3/templates は、次のトップレベルフィールドを受け付けます。

フィールド	要件
definition	必須です。header、body、footer、buttons、省略可能な definitionVersion、省略可能な authenticationConfig を含みます。
category	省略可能です：UTILITY、MARKETING、または AUTHENTICATION。曖昧さを許容できる場合に限り、カテゴリの検出を任せるには省略します。
language	省略可能なロケールです。例：en_US。
creation_source	省略可能なソース文字列です。from-api が文書化されているデフォルト値です。
submit_for_review	省略可能なブール値です。デフォルトは false です。審査に出す前に、下書きを作成して検証してください。
sandbox	副作用を伴わない検証に使用する省略可能なブール値です。

リクエストのルートに name、channels、body、header、buttons、components を置かないでください。name は更新／レスポンスで使われる項目であり、現在の作成リクエストには含まれません。

{
  "category": "UTILITY",
  "language": "en_US",
  "definition": {
    "header": null,
    "body": {
      "multiChannel": {
        "type": "body",
        "template": "Hi {{0:variable}}, order {{1:variable}} has shipped.",
        "variables": [
          {
            "id": 0,
            "name": "customerName",
            "type": "variable",
            "props": {"sample": "Avery"}
          },
          {
            "id": 1,
            "name": "orderNumber",
            "type": "variable",
            "props": {"sample": "A-1042"}
          }
        ]
      },
      "sms": null,
      "whatsapp": null,
      "rcs": null
    },
    "footer": null,
    "buttons": null,
    "definitionVersion": "1.0",
    "authenticationConfig": null
  },
  "creation_source": "from-api",
  "submit_for_review": false,
  "sandbox": true
}

チャネルに依存しない本文には definition.body.multiChannel を使用します。sms、whatsapp、rcs は断片ではなく、チャネルごとの完全なオーバーライドです。各本文は 1,024 文字以内にしてください。

3. 変数を正確に定義する

{{0:variable}}、{{1:link}}、{{2:media}} などのプレースホルダーを使用します。各プレースホルダーには、次の条件を満たす定義を 1 つずつ設定する必要があります。

• 一意の非負整数 id。
• わかりやすい name。
• 一致する type。
• 審査とプレビューに使う現実的なデータを含む props.sample。

すべての本文オーバーライドで、プレースホルダー ID と変数 ID を一致させてください。Sent のリクエストに、裸の {{1}} プレースホルダーを出力しないでください。

4. サポートされているボタンを追加する

Sent が現在認識するボタンは QUICK_REPLY、URL、VOICE_CALL、PHONE_NUMBER、COPY_CODE です。次の制限を守ってください。

• ボタンは合計 10 個まで。
• URL ボタンは最大 2 個。
• 音声通話ボタンは最大 1 個。
• 電話番号ボタンは最大 1 個。
• コードコピーのボタンは最大 1 個。
• クイック返信は、合計 10 個まで残りの枠を使用できます。

ボタンには id、type、props を設定します。ラベルは 25 文字以内です。タイプごとに必要なプロパティを指定してください：quickReplyType、urlType と url、countryCode と phoneNumber、または offerCode。クイック返信と行動喚起ボタンは併用できます。排他的論理和のルールを勝手に設けないでください。

5. 認証テンプレートを処理する

AUTHENTICATION では、definition.authenticationConfig を使用します。

{
  "addSecurityRecommendation": true,
  "codeExpirationMinutes": 10
}

有効期限は 1～90 分です。認証コンテンツは認証の目的に限定し、コード変数を 1 つと、サポートされているコードコピーアクションを使用してください。マーケティング文言、無関係なリンク、メディア、プロモーションボタンは追加しないでください。

6. 送信前に検証する

以下を実行します。

python scripts/lint_waba_template.py template.json

リンターは、Sent リクエストの形式、変数、1,024 文字の上限、チャネルのオーバーライド、現在のすべてのボタンタイプ、タイプごとの上限、認証設定を検証します。components[] を含む Meta Cloud API の例は、明示的な変換エラーで失敗する必要があります。

統合中は sandbox: true と submit_for_review: false を使用してください。ユーザーがプロバイダーのレビューを希望したら、最終的なペイロードを表示し、先に進む前に送信によって外部の状態が変更されることを説明してください。

7. 適切なライフサイクルの対象を追跡する

Sent テンプレートリソースでは、既知の状態として DRAFT、PENDING、APPROVED、REJECTED、PAUSED が使用されます。API が今後返すすべての値を網羅していると主張しないでください。

テンプレートの Webhook は WhatsApp の承認イベントです。field: "templates" を使用し、sub_type と event は省略して、プロバイダーのステータスを payload.status に格納します。

{
  "field": "templates",
  "timestamp": "2026-08-09T12:00:00Z",
  "payload": {
    "account_id": "00000000-0000-0000-0000-000000000000",
    "template_id": "11111111-1111-1111-1111-111111111111",
    "template_name": "order_update",
    "whatsapp_template_id": "2222222222222222",
    "status": "APPROVED",
    "language": "en_US",
    "category": "UTILITY",
    "channel": "whatsapp",
    "reason": null
  }
}

転送される一般的な値には、PENDING、APPROVED、REJECTED、CATEGORY_UPDATED があります。Meta は PAUSED や DISABLED などの値を送信することもあります。生の文字列を保存し、既知の値を処理して、不明な値も安全に表示してください。references/template-rejection-playbook.md を参照してください。

境界

エディターのアーキテクチャとクライアント側の検証 UX には template-builder-ui を使用してください。接続済みの Sent ツールを通じて既存のテンプレートを一覧表示、確認、削除するには sent-templates を使用してください。WABA の接続には waba-embedded-signup を使用してください。現在の RCS のローンチ機能には rcs-agent-onboarding を使用してください。

Meta Cloud API のペイロードが references/waba-template-examples.md に記載されている場合がありますが、そのような例にはすべて Sent ではないことを明記し、有効なリクエストとして Sent リンターに渡してはいけません。