範本元件

範本由四個主要元件組成，分別是標題、正文、頁尾和按鈕；您會在建立範本時定義這些元件。您應根據業務需要來決定要為每個範本選擇使用哪些元件。正文元件是唯一一項必要元件。

部分元件支援變數。當您使用雲端 API 或內部部署 API 透過範本訊息傳送範本時，您就可以提供這些變數的值。如您的範本使用變數，您必須在建立範本時加入變數值範例。

標題

標題是出現在範本訊息頂部的選用元件。標題支援文字、媒體（圖片、影片、文件）和位置。範本僅限包含 1 個標題元件。

文字標題

語法

{
  "type": "HEADER",
  "format": "TEXT",
  "text": "<TEXT>",

  # Required if <TEXT> string contains variables
  "example": {
    "header_text": [
      "<HEADER_TEXT>"
    ]
  }
}

屬性

範例

{
  "type": "HEADER",
  "format": "TEXT",
  "text": "Our {{1}} is on!",
  "example": {
    "header_text": [
      "Summer Sale"
    ]
  }
}

媒體標題

媒體標題可以是圖片、影片或 PDF 等文件。所有媒體都必須使用可恢復的上載 API 進行上載。定義媒體標題所用的語法同樣適用於所有媒體類型。

語法

{
  "type": "HEADER",
  "format": "<FORMAT>",
  "example": {
    "header_handle": [
      "<HEADER_HANDLE>"
    ]
  }
}

屬性

範例

{
  "type": "HEADER",
  "format": "IMAGE",
  "example": {
    "header_handle": [
      "4::aW..."
    ]
  }
}

位置標題

位置標題以一般地圖的形式出現在範本頂部，可用於訂單追蹤、送貨情況更新、叫車上落客情況、定位實體店等目的。點按後，應用程式用戶的預設地圖應用程式將開啟，並載入指定的位置。位置可在使用雲端 API 或內部部署 API 傳送範本時指定。

位置標題只能用於歸類為 UTILITY 或 MARKETING 的範本。不支援即時位置。

語法

{
  "type": "HEADER",
  "format": "LOCATION"
}

屬性

屬性值無法自訂。

範例

{
  "type": "HEADER",
  "format": "LOCATION"
}

正文

正文元件是所有範本所必要的純文字元件。模板僅限包含一個正文元件。

語法

{
  "type": "BODY",
  "text": "<TEXT>",
  
  # Required if <TEXT> string contains variables
  "example": {
    "body_text": [
      [
        <BODY_TEXT>
      ]
    ]
  }
}

屬性

範例

{
  "type": "BODY",
  "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
    "example": {
      "body_text": [
        [
          "the end of August","25OFF","25%"
        ]
      ]
    }
}

頁尾

頁尾是選用的純文字元件，緊接在正文元件後出現。範本僅限包含 1 個頁尾元件。

語法

{
  "type": "FOOTER",
  "text": "<TEXT>"
}

屬性

範例

{
  "type": "FOOTER",
  "text": "Use the buttons below to manage your marketing subscriptions"
}

按鈕

按鈕是選用的互動式元件，會在有人點按時執行特定的操作。範本最多可擁有 10 個不同按鈕元件，但同類的單個按鈕和組合按鈕均有限制。這些限制如下所示。

按鈕需在單個按鈕元件物件內定義，並併入單個 buttons 陣列中。例如，此範本使用電話號碼按鈕和網址按鈕：

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "PHONE_NUMBER",
      "text": "Call",
      "phone_number": "15550051310"
    },
    {
      "type": "URL",
      "text": "Shop Now",
      "url": "https://www.luckyshrub.com/shop/"
    }
  ]
}

如果一個範本包含多於三個按鈕，其中兩個按鈕會顯示在送達的訊息中，剩餘按鈕將替換為查看所有選項按鈕。點按查看所有選項，即可顯示剩餘按鈕。

複製代碼按鈕

應用程式用戶點按複製代碼按鈕後，此按鈕會將文字字串（在範本訊息中傳送範本時定義）複製到裝置的剪貼簿。範本僅限包含 1 個複製代碼按鈕。

語法

{
  "type": "COPY_CODE",
  "example": "<EXAMPLE>"
}

屬性

範例

{
  "type": "COPY_CODE",
  "example": "250FF"
}

Flows 按鈕

Flows 按鈕用於將 Flows 訊息作為範本傳送。範本僅限包含 1 個 Flows 按鈕。

您可在遊樂場迅速建立 Flow 並以 JSON 格式附上，或者指定現有的 Flow 編號。

語法

{
  "type": "FLOW",
  "text": "<TEXT>",
  "flow_id": "<FLOW_ID>",
  "flow_json": "<FLOW_JSON>", 
  "flow_action": "<FLOW_ACTION>",
  "navigate_screen": "<NAVIGATE_SCREEN>"
}

屬性

範例

{
  "type": "FLOW",
  "text": "Sign up",
  "flow_action": "navigate",
  "navigate_screen": "WELCOME_SCREEN"
  "flow_json" : {
    "version": "3.1",
    "screens": [
        {
            "id": "WELCOME_SCREEN",
            "layout": {
                "type": "SingleColumnLayout",
                "children": [
                    {
                        "type": "TextHeading",
                        "text": "Hello World"
                    },
                    {
                        "type": "TextBody",
                        "text": "Let's start building things!"
                    },
                    {
                        "type": "Footer",
                        "label": "Complete",
                        "on-click-action": {
                            "name": "complete",
                            "payload": {}
                        }
                    }
                ]
            },
            "title": "Welcome",
            "terminal": true,
            "success": true,
            "data": {}
        }
    ]
  }
}

多商品訊息按鈕

多商品訊息（MPM）按鈕是無法自訂的特殊按鈕。點按此按鈕時，單一訊息中會顯示電子商務目錄內最多 30 項商品的相關資訊，最多可分為 10 個部分。查看多商品訊息範本。

單次密碼按鈕

單次密碼（OTP）按鈕是指一種特殊類型的網址按鈕元件，需與驗證類別範本一同使用。請參閱驗證類別範本。

電話號碼按鈕

應用程式用戶點按電話號碼按鈕時，此按鈕會撥打指定的商家電話號碼。範本僅限包含 1 個電話號碼按鈕。

語法

{
  "type": "PHONE_NUMBER",
  "text": "<TEXT>",
  "phone_number": "<PHONE_NUMBER>"
}

屬性

範例

{
  "type": "PHONE_NUMBER",
  "text": "Call",
  "phone_number": "15550051310"
}

快速回覆按鈕

快速回覆按鈕是自訂的純文字按鈕，在應用程式用戶點按時，此按鈕會立即向您傳送包含指定文字字串的訊息。常見的使用案例之一，是用作能讓顧客輕鬆取消訂閱任何營銷訊息的按鈕。

範本僅限包含 10 個快速回覆按鈕。如將快速回覆按鈕與其他按鈕配合使用，這些按鈕必須分為兩組：快速回覆按鈕和非快速回覆按鈕。如分組錯誤，API 將傳回錯誤，表示組合無效。

有效組合範例：

• 快速回覆、快速回覆
• 快速回覆、快速回覆、網址、電話
• 網址、電話、快速回覆、快速回覆

無效組合範例：

• 快速回覆、網址、快速回覆
• 網址、快速回覆、網址

使用雲端 API 或內部部署 API 傳送包含多個快速回覆按鈕的範本時，您可以使用索引屬性指定按鈕在範本訊息中的出現順序。

語法

{
  "type": "QUICK_REPLY",
  "text": "<TEXT>"
}

屬性

範例

{
  "type": "QUICK_REPLY",
  "text": "Unsubscribe from Promos"
}

單一商品訊息按鈕

單一商品訊息（SPM）按鈕是無法自訂的特殊按鈕，可對應商品目錄中的特定商品。點按此按鈕時，系統會從您的目錄擷取資料，並載入關商品詳情。然後，用戶可以將商品加入購物車並提交訂單。查看單一商品訊息範本和商品圖卡輪播廣告範本。

網址按鈕

應用程式用戶點按網址按鈕時，此按鈕會在裝置的預設網頁瀏覽器中載入指定的網址。範本僅限包含 2 個網址按鈕。

語法

{
  "type": "URL",
  "text": "<TEXT>",
  "url": "<URL>",

  # Required if <URL> contains a variable
  "example": [
    "<EXAMPLE>"
  ]
}

屬性

範例

{
  "type": "URL",
  "text": "Shop Now",
  "url": "https://www.luckyshrub.com/shop?promo={{1}}",
  "example": [
    "summer2023"
  ]
}

限時優惠

限時優惠元件是用於建立限時優惠範本的特別元件。

要求範本

季節性促銷

使用以下元件建立營銷範本的要求範例：

• 1 個包含變數和值範例的文字標題
• 1 個包含變數和值範例的文字正文
• 1 個文字頁尾
• 2 個快速回覆按鈕

curl -L 'https://graph.facebook.com/v21.0/102290129340398/message_templates' \
-H 'Authorization: Bearer EAAJB...' \
-H 'Content-Type: application/json' \
-d '
{
  "name": "seasonal_promotion",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Our {{1}} is on!",
      "example": {
        "header_text": [
          "Summer Sale"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
      "example": {
        "body_text": [
          [
            "the end of August","25OFF","25%"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Use the buttons below to manage your marketing subscriptions"
    },
    {
      "type":"BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Unsubscribe from Promos"
        },
        {
          "type":"QUICK_REPLY",
          "text": "Unsubscribe from All"
        }
      ]
    }
  ]
}'

訂單確認

使用以下元件建立工具類別範本的要求範例：

• 1 個包含值範例的文件標題
• 1 個包含變數和值範例的文字正文
• 1 個電話號碼按鈕
• 1 個網址按鈕

curl -L 'https://graph.facebook.com/v16.0/102290129340398/message_templates' \
-H 'Authorization: Bearer EAAJB...' \
-H 'Content-Type: application/json' \
-d '
{
  "name": "order_confirmation",
  "language": "en_US",
  "category": "UTILITY",
  "components": [
    {
      "type": "HEADER",
      "format": "DOCUMENT",
      "example": {
        "header_handle": [
          "4::YX..."
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Thank you for your order, {{1}}! Your order number is {{2}}. Tap the PDF linked above to view your receipt. If you have any questions, please use the buttons below to contact support. Thank you for being a customer!",
      "example": {
        "body_text": [
          [
            "Pablo","860198-230332"
          ]
        ]
      }
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "PHONE_NUMBER",
          "text": "Call",
          "phone_number": "15550051310"
        },
        {
          "type": "URL",
          "text": "Contact Support",
          "url": "https://www.luckyshrub.com/support"
        }
      ]
    }
  ]
}'

訂單送貨情況更新

使用以下元件建立工具類別範本的要求範例：

• 1 個位置標題
• 1 個包含變數和值範例的文字正文
• 1 個頁尾
• 1 個快速回覆按鈕

curl 'https://graph.facebook.com/v21.0/102290129340398/message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "name": "order_delivery_update",
  "language": "en_US",
  "category": "UTILITY",
  "components": [
    {
      "type": "HEADER",
      "format": "LOCATION"
    },
    {
      "type": "BODY",
      "text": "Good news {{1}}! Your order #{{2}} is on its way to the location above. Thank you for your order!",
      "example": {
        "body_text": [
          [
            "Mark",
            "566701"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "To stop receiving delivery updates, tap the button below."
    },
    {
      "type":"BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Stop Delivery Updates"
        }
      ]
    }
  ]
}'

元件更新 Webhook

訂閱 message_template_components_update Webhook 欄位，以接收有關範本元件變更的通知，例如變更標題／正文或新增按鈕。

Webhook 回覆形狀

"message_template_id": <id>,
"message_template_name": <string>,
"message_template_language": <string>,
"message_template_title": <string>,
"message_template_element": <string>,
"message_template_footer": <string>,
"message_template_buttons": [
  {
    "message_template_button_type": <string>,
    "message_template_button_text": <string>,
    "message_template_button_url": <string>,
    "message_template_button_phone_number": <string>
  }
]

Webhook 回應範例

"message_template_id": 1234567890,
"message_template_name": “promo_summer_sale_11_en”,
"message_template_language": “en_US”,
"message_template_title": “header”,
"message_template_element": “body”,
"message_template_footer": “footer”,
"message_template_buttons": [
  {
    "message_template_button_type": URL,
    "message_template_button_text": “click me”,
    "message_template_button_url": “https://www.example.com”,
    "message_template_button_phone_number": “+1(123)4565678”
  }
]

Webhook 回覆欄位