建立及管理範本

在借助由 Meta 託管的雲端 API 或內部部署 API 傳送訊息範本時會用到範本。雲端 API 會使用機器學習技術審查範本和變數參數，以保護雲端 API 服務的安全性和完整性。雲端 API 審查範本和變數文字時，不會與 WhatsApp 分享任何資料。

您可以使用 Business Management API 或 WhatsApp Business 管理工具建立範本。WhatsApp Business 帳戶可以擁有的範本數量取決於該帳戶的母公司。如果總公司未經驗證，則旗下每個 WhatsApp Business 帳戶最多可擁有 250 個範本。不過，如果總公司已通過驗證，而且最少有一個 WhatsApp Business 帳戶使用帶有獲批准顯示名稱的公司電話號碼，則旗下每個 WhatsApp Business 帳戶最多可擁有 6,000 個範本。

準備工作

您需要準備以下事項：

• 連結至企業的系統用戶存取憑證。
• whatsapp_business_management 權限。
• 企業的 WhatsApp Business 帳戶編號。
• 要在媒體範本中使用的任何文件、圖片或影片檔案的媒體素材用戶名稱。如要獲取媒體素材用戶名稱，您必須使用可恢復的上載 API 來上載媒體素材。

限制

• 訊息範本名稱欄位限制為 512 個字元。
• 訊息範本內容欄位限制為 1024 個字元。
• 只有處於已核准、已拒絕或已暫停狀態的範本方可供編輯。範本每天可供編輯一次，每月最多可供編輯 10 次。
• WhatsApp Business 帳戶每小時只能建立 100 個訊息範本。
• 如果範本由 4 個或以上按鈕組成，或由 1 個快速回覆按鈕和 1 個或以上其他類型的按鈕組成，則 WhatsApp 桌面版用戶無法查看此範本。如果 WhatsApp 用戶收到以上其中一則範本訊息，系統會提示用戶改為在手機上查看訊息。

本地化

您可以在建立範本時新增特定語言的訊息範本。這些範本會計入您的範本數量上限。提供翻譯時，請確保一致性。詳情請查看為什麼我的回呼出現「無法找到結構」錯誤？幫助中心文章。

建立範本

傳送 POST 要求至 WhatsApp Business 帳戶 > 訊息範本端點來建立範本。

要求語法

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates

帖子內文

{
  "name": "<NAME>",
  "category": "<CATEGORY>",
  "allow_category_change": <ALLOW_CATEGORY_CHANGE>,
  "language": "<LANGUAGE>",
  "components": [<COMPONENTS>]
}

內文屬性

範本類別

範本必須歸類為以下其中一個類別。類別會影響定價，您指派的類別會在建立範本時完成驗證。

• AUTHENTICATION
• MARKETING
• UTILITY

請參閱我們的範本分類文件，以確定在建立範本時使用哪個類別。

範本元件

範本可由多種文字、媒體和互動式元件構成，具體視乎您的企業需要而定。請參閱範本元件文件，以了解所有可行元件的清單及其對應要求，以及查閱範例和查詢例子。

在建立範本時，您可以為要求內文中的 components 屬性指派元件物件陣列來定義其元件。

例如，此處的陣列包含一個內文元件（含兩個變數和值範例）、一個「電話號碼」按鈕元件和一個「網址」按鈕元件：

[
  {
    "type": "BODY",
    "text": "Thank you for your order, {{1}}! Your confirmation number is {{2}}. 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"
      }
    ]
  }
]

請參閱範本元件文件，以了解所有可行元件的清單及其對應要求，以及查閱範例和查詢例子。

請注意，分類為 AUTHENTICATION 的範本有其獨特的元件規定。請參閱驗證類別範本。

驗證類別

當您傳送範本建立要求時，我們會立即根據範本分類守則來確認其類別。

• 如果我們同意您指定的類別，便會建立範本，並將其 status 設為 PENDING。該範本隨即會接受範本審查。
• 如果我們不同意您指定的類別，則會建立範本，但將其 status 設為 REJECTED 並觸發訊息範本狀​​態更新 Webhook，其中 reason 設定為 INCORRECT_CATEGORY。我們建議您聽取此 Webhook 以識別被拒的範本，或者在新建立的範本上索取 rejected_reason 欄位，該欄位的值應為 TAG_CONTENT_MISMATCH。

在這兩種情況下，API 回應會傳回範本的初始狀態。

如果經類別驗證後，您的範本狀態設為 REJECTED，您有數種選項：

• 編輯範本元件，使其符合我們的守則。
• 編輯範本類別，使其符合我們的守則。
• 建立新範本。

自動分類

您可以在要求中納入 allow_category_change 屬性，以便我們根據範本內容和範本分類守則自動指派類別。這樣做可避免您的範本狀態因分類錯誤而立即被系統設為 REJECTED。

請注意，自動分類只適用於建立範本程序。

範本審查

狀態為 PENDING 的範本即正在接受範本審查。我們會審查每個新建立或編輯範本的內容，以確保範本符合我們的內容守則和政策規定。根據審查結果，我們會自動將範本狀態變更為 APPROVED 或 REJECTED，這會觸發訊息範本狀​​態更新 Webhook。

範本狀態

根據類別驗證和範本審查的結果，我們會將您範本的 status 設定或變更為下列值之一：

• APPROVED：範本已通過範本審查並獲核准，現在可以以範本訊息形式傳送。
• PENDING：範本已通過類別驗證，正在接受範本審查。
• REJECTED：範本未能通過類別驗證或範本審查。您可以索取範本的 rejected_reason 欄位來了解原因。

請參閱 WhatsApp 訊息範本端點參考資料，查看所有可用的欄位及狀態。

回應

成功的話，API 回應中將會包含新建立範本的編號、狀態和類別。可能會有三種結果：

• 我們同意您指定的類別，範本目前正在接受範本審查（status 為 PENDING）。
• 我們不同意您指定的類別（status 為 REJECTED）。
• 我們已自動核准範本（status 為 APPROVED）。這僅適用於設有單次密碼按鈕的驗證類別範本。

{
    "id": "<ID>",
    "status": "<STATUS>",
    "category": "<CATEGORY>"
}

回應屬性

要求範例

以下要求範例展示了如何建立包含以下元素的季節性推廣活動範本：

• 1 個文字標題
• 1 個內文
• 1 個頁尾
• 2 個快速回覆按鈕

如需了解其他範本，請參閱要求範例。

curl '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"
        }
      ]
    }
  ]
}'

回應範例

{
    "id": "572279198452421",
    "status": "PENDING",
    "category": "MARKETING"
}

傳送範本

使用雲端 API 或內部部署 API，透過範本訊息傳送範本。

存留時間（TTL）：自訂值、預設值、最小／最大值和相容性

如果訊息無法成功傳送至 WhatsApp 用戶，我們會在一段時間內再次嘗試傳送此訊息。這段時間稱為「存留時間」，或訊息有效期限。

您可自訂驗證範本、工具範本和營銷範本的預設留存時間。

建議您為自己所有驗證範本都設定存留時間，最好不要超過驗證碼有效期，從而確保顧客只會在驗證碼仍然可用時收到訊息。

預設值、最小／最大值和安全性表格

自訂範本存留時間的方法

如要設定驗證範本、工具範本或營銷範本的自訂存留時間，請在 POST /<PHONE_NUMBER_ID>/messages 呼叫中加入並設定 message_send_ttl_seconds 屬性值。

您可根據自身需求，以秒為單位增加存留時間。

有效的 message_send_ttl_seconds 屬性值

• 驗證範本：30 至 900 秒（30 秒至 15 分鐘）
• 工具範本：30 至 43200 秒（30 秒至 12 小時）
• 營銷範本：43200 至 2592000（12 小時至 30 天）

將驗證範本和工具範本的 message_send_ttl_seconds 屬性值設定為 -1，便可將存留時間自訂為 30 天。

當超出存留時間：被放棄的訊息

當訊息無法在預設或自訂存留時間內送達，系統便會捨棄該訊息。

如果您在存留時間期內沒有收到訊息已送達 Webhook，便可假設系統已放棄該訊息。

假如您發出的訊息未能送達，您可能略有延遲才收到該 Webhook。因此，您可能需要預留一小段緩衝時間，才假定系統已放棄訊息。

營銷範本的最佳操作實例

營銷訊息退訂按鈕

我們建議您在劃入 MARKETING 類別的範本加入「快速回覆」按鈕，以便顧客輕鬆退訂營銷訊息。這讓顧客可以選擇在不封鎖您企業的情況下退訂您的營銷訊息。如此一來，您便可以更快地擴大訊息收發量。請參閱此文章，進一步了解在營銷範本加入「退訂」按鈕的好處。

取得範本

傳送 GET 要求至 WhatsApp Business 帳戶 > 訊息範本端點，以取得由 WhatsApp Business 帳戶擁有的範本清單。

要求語法

GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?fields=<FIELDS>
  &limit=<LIMIT>

查詢字串參數

要求範例

curl 'https://graph.facebook.com/v21.0/102290129340398/message_templates?fields=name,status&limit=3' \
-H 'Authorization: Bearer EAAJB...'

回應範例

{
  "data": [
    {
      "name": "seasonal_promotion_text_only",
      "status": "APPROVED",
      "id": "564750795574598"
    },
    {
      "name": "seasonal_promotion_video",
      "status": "PENDING",
      "id": "1252715608684590"
    },
    {
      "name": "seasonal_promotion_image_header",
      "status": "PENDING",
      "id": "1372429296936443"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MgZDZD"
    },
    "next": "https://graph.facebook.com/v21.0/102290129340398/message_templates?fields=name%2Cstatus&limit=3&after=MgZDZD"
  }
}

要求範例（被拒範本）

您可以在要求中加入特定欄位和所需的值，只傳回具有相應欄位值的範本。舉例來說，加入 status=REJECTED 可只取得被拒範本。

curl 'https://graph.facebook.com/v21.0/104996122399160/message_templates?fields=name,status&status=REJECTED' \
-H 'Authorization: Bearer EAAJB...'

回應範例

{
  "data": [
    {
      "name": "seasonal_promotion_text_only_v4",
      "status": "REJECTED",
      "id": "564750795574598"
    },
    {
      "name": "discount_qualifier",
      "status": "REJECTED",
      "id": "163917509772674"
    },
    {
      "name": "limited_time_offer_tuscan_getaway_2023",
      "status": "REJECTED",
      "id": "202389039167147"
    },
    {
      "name": "2023_mar_promo_2",
      "status": "REJECTED",
      "id": "1116034925734553"
    },
    {
      "name": "2023_mar_promo",
      "status": "REJECTED",
      "id": "952600926095321"
    }
  ]
}

檢索範本命名空間

如要使用訊息範本來傳送訊息，則須使用訊息範本命名空間。

如要取得範本的命名空間，請向 /{whatsapp-business-account-ID} 端點傳送 GET 要求並加入 message_template_namespace 欄位。

要求範例

curl -i -X GET "https://graph.facebook.com/v21.0/{whatsapp-business-account-ID}
  ?fields=message_template_namespace
  &access_token={system-user-access-token}"

成功的話，系統會傳回一個帶有 WhatsApp Business 帳戶編號和命名空間的 JSON 物件：

{
    "id": "1972385232742141",
    "message_template_namespace": "12abcdefghijk_34lmnop" 
}

編輯範本

傳送 POST 要求至 WhatsApp 訊息範本端點來編輯範本。您亦可使用 WhatsApp 管理工具 > 帳戶工具 > 訊息範本面板來手動編輯範本。

限制

• 只能編輯 APPROVED、REJECTED 或 PAUSED 狀態的範本。
• 您只能編輯範本的 category 或 components。
• 您無法編輯已批准範本的 category。
• 已批准範本可在連續 30 天內最多編輯 10 次，或每 24 小時最多編輯 1 次。已被拒或已暫停的範本可以編輯無限次。
• 除非未能通過審查，否則經您編輯後的已批准或已暫停範本都會自動獲得批准。

要求語法

POST /<WHATSAPP_MESSAGE_TEMPLATE_ID>

帖子內文

{
  "category": "<CATEGORY>",
  "components": [<COMPONENTS>]
}

屬性

要求範例（編輯元件）

要求範例，要求同時包含營銷和工具內容的範本正文只包含營銷內容。

curl 'https://graph.facebook.com/v21.0/564750795574598' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Our {{1}} is on!",
      "example": {
        "header_text": [
          "Spring 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 April",
            "25OFF",
            "25%"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Use the buttons below to manage your marketing subscriptions"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Unsubcribe from Promos"
        },
        {
          "type": "QUICK_REPLY",
          "text": "Unsubscribe from All"
        }
      ]
    }
  ]
}'

要求範例（僅編輯類別）

要求範例，要求將範本的類別從 UTILITY 變更為 MARKETING。

curl 'https://graph.facebook.com/v21.0/1252715608684590' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "category": "MARKETING"
}'

回應範例

成功時的回應範例。

{
  "success": true
}

刪除範本

使用 WhatsApp Business 帳戶 > 訊息範本端點來按名稱或編號刪除範本。

備註

• 如果您刪除已在訊息範本中傳送但尚未送達的範本（例如由於顧客的手機關機），此範本的狀態將被設為 PENDING_DELETION，並且我們將嘗試在 30 天內送達此訊息。此時段過後，您會收到「無法找到結構」錯誤，並且顧客將不會收到此訊息。
• 經刪除後，已批准範本的名稱無法在 30 天內再次使用。

按名稱刪除

按名稱刪除範本會刪除所有與該名稱相符的範本，即名稱相同但語言不同的範本也會被刪除。

要求語法

DELETE /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?name=<NAME>

要求範例

curl -X DELETE 'https://graph.facebook.com/v16.0/102290129340398/message_templates?name=order_confirmation' \
-H 'Authorization: Bearer EAAJB...'

回應範例

{
  "success": true
}

按編號刪除

如要按編號刪除範本，請在要求中加入範本編號及其名稱；系統只會刪除具有相符範本編號的範本。

要求語法

DELETE /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?hsm_id=<HSM_ID>,
  &name=<NAME>

要求範例

curl -X DELETE 'https://graph.facebook.com/v21.0/102290129340398/message_templates?hsm_id=1407680676729941&name=order_confirmation' \
-H 'Authorization: Bearer EAAJB...'

回應範例

{
  "success": true
}

詳細了解

後續步驟

• 開始使用雲端 API 著手傳送訊息