Skip to content

WhatsApp テンプレートビルダーでの Liquid

WhatsApp テンプレートビルダーでテンプレートをパーソナライズするために Liquid を使用できますが、Meta のテンプレート構造には他の Braze チャネルにはない制約があります。特にメッセージエクストラと条件付きメッセージングロジックの2つの Liquid パターンには特別な対応が必要です。

メッセージエクストラと条件付きメッセージングロジックについて、Meta はテンプレート内の各変数が送信時に実際にレンダリングされたコンテンツを含むことを要求します。空の文字列を取得する変数や、表示テキストではなく非表示のメタデータとして機能する変数は、送信失敗の原因となります。静的なメッセージ構造を変更する条件文（変数のコンテンツのみを変更するのではなく）も、予期しない動作を引き起こします。

概要

パターン サポート状況 備考
他の表示コンテンツと一緒に変数内に message_extras を配置 ✅ はい タグがキャプチャされ、表示テキストが Meta の変数コンテンツ要件を満たします
変数の唯一のコンテンツとして message_extras を配置 ❌ いいえ 空の文字列に解決され、送信失敗の原因となります
変数スロット内の条件付き Liquid ✅ はい Braze が送信前に評価し、Meta は最終的なレンダリング値のみを認識します
変数スロット外の条件付き Liquid ❌ いいえ Liquid タグがリテラルテキストとしてレンダリングされ、受信者に生の構文が表示されます
変数スロットで始まるまたは終わるテンプレート ❌ いいえ Meta はすべてのテンプレートの先頭と末尾に静的テキストを要求します
空の文字列に解決される変数スロット ❌ いいえ Meta は送信時にすべての変数に空でないコンテンツを要求します

メッセージエクストラ

message_extras Liquid タグを使用すると、送信時にキーバリューメタデータでメッセージに注釈を付けることができます。このデータはメッセージ本文にはレンダリングされません。代わりに、アトリビューション、影響測定、イベントエンリッチメントなどの目的で、コネクテッドコンテンツ、Currents、またはその他のデータキャプチャメカニズムにデータが流れます。

1

{% message_extras :key campaign_id :value "spring_promo_2025" %}

スタンドアロンのメッセージエクストラ変数が失敗する理由

WhatsApp テンプレートビルダーでは、テンプレート変数（{{1}}、{{2}} など）は Liquid 式に直接マッピングされます。Meta のバリデーションでは、承認済みテンプレート内のすべての変数スロットが送信時に空でないコンテンツを含むことを要求します。つまり、受信者に表示テキストとしてレンダリングされるものでなければなりません。

message_extras は出力をレンダリングしないため、テンプレート変数内に単独で配置すると、その変数スロットに空の文字列が送信されます。Meta はこれを拒否するため、メッセージの送信が失敗します。

WhatsApp テンプレートビルダーでの誤った使用方法
1

Template variable {{1}}: {% message_extras :key attribution_source :value "canvas_a" %}

送信時に {{1}} が空の文字列に解決され、送信失敗の原因となります。

正しい使用方法

message_extras タグを正しく含めるには、既存の変数にタグを埋め込みます。つまり、表示出力を生成する Liquid ブロック内、具体的には実際のテンプレート変数を設定する同じ式内にタグを配置します。Meta は変数にコンテンツが含まれているため受け入れ、Braze はメタデータをキャプチャし、受信者にはレンダリングされたテキストのみが表示されます。

例

テンプレート本文が以下のようになっているとします:

1

Hi {{1}}, your order has shipped.

変数 {{1}} が以下にマッピングされているとします:

1

{{ ${first_name} | default: "there" }}

メッセージエクストラを添付するには、変数式を以下のように書き換えます:

1

{{ ${first_name} | default: "there" }}{% message_extras :key order_source :value "canvas_spring" %}

送信時に {{1}} は "Alex" のような値に解決され、Meta の要件を満たす表示コンテンツとなります。message_extras タグは評価されてデータがキャプチャされますが、受信者に表示されるレンダリング文字列には何も寄与しません。

主なルール

  • message_extras をテンプレート変数の唯一のコンテンツとして割り当てないでください。
  • 常に表示テキストに解決される変数にタグを添付してください。
  • レンダリング出力に影響を与えることなく、同じ変数式に複数の message_extras タグを追加できます。
  • このパターンは本文、ヘッダー、その他の変数スロットで使用できます。

条件付きメッセージングロジック

メッセージングチャネルでは、Liquid の if/elsif/else ブロックを使用して、テキストのセクション全体を条件付きで含めたり除外したりできます。Braze は送信前に完全な Liquid 出力をレンダリングし、結果はロジックが生成したものになります。

ただし、Meta 承認済みの WhatsApp テンプレートには固定構造があります。Meta はテンプレートコンテンツを2つのカテゴリーで考えます:

  • 静的テキスト: テンプレート作成時に確認され、すべての受信者に対して同一のままであるハードコードされた文字列。
  • 変数スロット: 送信時にコンテンツが入力されるプレースホルダー位置（{{1}} など）。

変数スロット外の条件付きメッセージングロジックが失敗する理由

承認済みテンプレートにおける静的テキストと変数スロットの比率は固定されており、送信ごとに変更できず、厳格な制限があります。Meta はテンプレート内のすべての変数スロットに対して最低限の静的テキストを要求します。ほとんどまたはすべてが変数で構成されるテンプレートは作成できません。つまり、Meta が確認済みの静的コンテンツと見なすテキストを追加または削除する条件付き Liquid を含めることはできません。

if/else ブロックを使用して静的テキストのチャンクを条件付きで含めたり除外したりしようとしても、Meta はそのロジックを評価しません。変数スロット外の Liquid タグはリテラル出力テキストとして扱われます。受信者には生の Liquid 構文タグ（{% if %}、{% else %}、{% endif %}）とすべてのブランチコンテンツがそのままメッセージに表示されます。

WhatsApp テンプレートビルダーでの誤った使用方法
1

{% if ${loyalty_tier} == "gold" %}Hi {{1}}, we have an exclusive Gold member offer.{% else %}Hi {{1}}, we have a special offer for you.{% endif %}

これは2つの異なる承認済みテンプレートを1つに含めようとしています。静的テキストを囲む条件文は期待どおりに動作しません。

正しい使用方法

条件文は変数スロット内で有効かつサポートされており、その変数に入る値を制御します。Meta は {{1}} にコンテンツが設定されたことのみを認識し、内部の Liquid がどのようにその値に到達したかは検査しません。

例

1

{% if ${loyalty_tier} == "gold" %}exclusive Gold member{% else %}valued customer{% endif %}

テンプレート変数の値として使用すると、"exclusive Gold member" または "valued customer" のいずれかが生成されます。どちらも Meta の変数コンテンツ要件を満たす空でない文字列です。

テンプレート本文自体は構造的に変更されません:

1

Hi {{1}}, we have a special offer for you.

条件付きロジックを変数スロット内に配置する

テンプレートビルダーで条件付き Liquid を変数スロットに配置するには、2つの方法があります:

  1. Content Blocksを使用する（プリフィルをサポート）: 条件付きロジックをContent Blocks内に構築し、変数からそのブロックを参照します。このアプローチはプリフィルをサポートしており、送信前にテンプレートビルダーで変数にプレビュー値を表示できます。
  2. プレースホルダーを使用して Liquid を貼り付ける（プリフィルなし）: テンプレート作成時に {{1}} のようなプレースホルダーを追加し、その変数スロットに完全な Liquid 式を直接貼り付けます。このアプローチはプリフィルをサポートしませんが、あらゆる Liquid ロジックに対応します。

同じ制約の影響を受けるその他の Liquid コンポーネント

表示出力を生成しない Liquid タグは、変数外に配置された場合、生のテキストとしてレンダリングされます。これには以下が含まれます:

  • catalog_items: カタログデータを検索して参照する Liquid は変数スロット内に配置する必要があります。そうしないと、タグがメッセージにそのまま表示されます。
  • assign: 変数代入タグ（{% assign discount = “20%” %} など）はそれ自体では出力を生成しません。メッセージ内で後で使用する値を設定するために変数スロット外で使用すると、assign タグがそのままレンダリングされます。assign ロジックは、その出力が必要な変数スロット内の Liquid 式の先頭に含めてください。
  • Liquid タグのみを含むContent Blocks: Content Blocksに Liquid ロジックが含まれているが表示テキストを生成しない場合（例えば、assign や message_extras タグのみを使用している場合）、変数スロット外でそれを参照すると、生のブロックコンテンツがメッセージに表示されます。表示出力を生成しないContent Blocksは、レンダリングされるコンテンツと一緒に変数スロット内に埋め込む必要があります。

その他の構造的制約

Meta はテンプレートに以下を要求します:

  • 静的テキストで始まること。 テンプレートは変数スロットで始めることはできません（{{1}} is ready for you など）。
  • 静的テキストで終わること。 テンプレートは変数スロットで終わることはできません。

これらの制約は Liquid の使用に関係なく存在します。承認済みテンプレート構造自体に適用されます。

主なルール

  • 変数スロット式内で条件文を自由に使用して、レンダリングされる値を制御できます。
  • 静的テキスト（メッセージの変数スロットではない部分）を追加、削除、または入れ替えるために条件文を使用しないでください。
  • 変数内のすべての条件分岐が空でない文字列を生成することを確認してください（空の文字列が失敗を引き起こす理由についてはメッセージエクストラを参照してください）。
  • テンプレートは Meta に送信される際、静的テキストで始まり、静的テキストで終わる必要があります。
New Stuff!