使用雲端 API(Meta 託管)或內部部署 API 傳送範本訊息時,系統會使用範本。雲端 API 使用機器學習來審核範本和變數參數,可保護雲端 API 服務的安全性和完整性。當雲端 API 審核範本和變數文字時,不會與 WhatsApp 分享任何資訊。
您可以使用 Business Management API 或 WhatsApp 企業管理平台建立範本。WhatsApp Business 帳號可擁有的範本數量由其母商家決定。若母商家尚未認證,其每個 WhatsApp Business 帳號僅限擁有 250 個範本。但若母商家已通過認證,且其至少一個 WhatsApp Business 帳號具有已核准顯示名稱的商家電話號碼,其每個 WhatsApp Business 帳號最多可擁有 6,000 個範本。
必備資料:
您可以在建立範本時,新增特定語言的訊息範本。這些範本會計入您的限制中。提供翻譯時,請保持一致性。請參閱為什麼在我的回呼中會顯示「結構無法使用」錯誤?使用說明文章,以瞭解詳情。
請傳送 POST 要求至 WhatsApp Business 帳號 > 訊息範本端點建立範本。
POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
{ "name": "<NAME>", "category": "<CATEGORY>", "allow_category_change": <ALLOW_CATEGORY_CHANGE>, "language": "<LANGUAGE>", "components": [<COMPONENTS>] }
預留位置 | 說明 | 範例值 |
---|---|---|
字串 | 必要項目。 範本名稱。 最多 512 個字元。 |
|
列舉 | 必要項目。 範本類別。 請參閱下文的範本類別。 |
|
布林值 | 選用項目。 設為 true,允許我們自動指派類別。如果省略,範本可能因分類錯誤而遭拒。 |
|
列舉 | 必要項目。 範本語言和地區設定代碼。 |
|
字串 | 選用項目。 「公用範本庫」範本的確切名稱。 瞭解如何使用公用範本庫來建立範本 |
|
物件陣列 | 選用項目。 範本中使用的商家網站和/或電話號碼。 注意:對於包含按鈕的公用範本,這不是選用屬性。 瞭解如何使用公用範本庫來建立範本 |
|
物件陣列 | 必要項目。 組成範本的元件。 請參閱下文的範本元件。 | 請參閱下文的範本元件。 |
必須使用下列類別其中之一將範本分類。類別會影響定價,且建立範本的同時將驗證您指定的類別。
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
設為 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
){ "id": "<ID>", "status": "<STATUS>", "category": "<CATEGORY>" }
這是建立季節性促銷活動範本的要求範例,由下列元件組成:
如需其他範例,請參閱範例要求。
curl 'https://graph.facebook.com/v19.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" }
傳送 GET 要求至 WhatsApp Business 帳號 > 訊息範本端點,可取得 WhatsApp Business 帳號擁有的範本清單。
GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates ?fields=<FIELDS> &limit=<LIMIT>
預留位置 | 說明 | 範例值 |
---|---|---|
逗號分隔的清單 | 選用項目。 要傳回的範本欄位清單。 |
|
整數 | 選用項目。 要在每頁結果中傳回的最大範本數量。 |
|
curl 'https://graph.facebook.com/v19.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/v19.0
/102290129340398/message_templates?fields=name%2Cstatus&limit=3&after=MgZDZD"
}
}
透過在要求中包含欄位和所需值,您可以僅傳回具有特定欄位值的範本。例如,包含 status=REJECTED
可以僅取得已拒絕的範本。
curl 'https://graph.facebook.com/v19.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" } ] }
必須要有訊息範本命名空間,才能使用訊息範本來傳送訊息。
若要取得範本的命名空間,請傳送 GET
要求至 /{whatsapp-business-account-ID}
端點,並包含 message_template_namespace
欄位。
curl -i -X GET "https://graph.facebook.com/v19.0
/{whatsapp-business-account-ID}
?fields=message_template_namespace
&access_token={system-user-access-token}"
如果成功,系統會傳回 JSON 物件以及 WhatsApp Business 帳號編號和命名空間:
{ "id": "1972385232742141", "message_template_namespace": "12abcdefghijk_34lmnop" }
請傳送 POST 要求至 WhatsApp 訊息範本端點編輯範本。您也可以使用 WhatsApp 管理工具 > 帳號工具 > 訊息範本面板手動編輯範本。
APPROVED
、REJECTED
或 PAUSED
的範本。category
或 components
。category
。POST /<WHATSAPP_MESSAGE_TEMPLATE_ID>
{ "category": "<CATEGORY>", "components": [<COMPONENTS>] }
預留位置 | 說明 | 範例值 |
---|---|---|
字串 | 若省略元件屬性,則為必要項目。 範本類別。 |
|
陣列 | 若省略類別屬性,則為必要項目。 範本元件物件的陣列。 | 請參閱下文的要求範例(編輯元件)。 |
此要求範例為同時包含行銷和公用內容的範本本文,以僅包含行銷內容。
curl 'https://graph.facebook.com/v19.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/v19.0
/1252715608684590' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
"category": "MARKETING"
}'
成功後的回應範例。
{ "success": true }
請使用 WhatsApp Business 帳號 > 訊息範本端點依名稱或依編號刪除範本。
PENDING_DELETION
,我們將嘗試在 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/v19.0
/102290129340398/message_templates?hsm_id=1407680676729941&name=order_confirmation' \
-H 'Authorization: Bearer EAAJB...'
{ "success": true }