驗證類別範本
由 2024 年 4 月 1 日起,任何現有驗證類別範本如不屬於已加入單次密碼按鈕的驗證類別範本,將無法加以傳送、編輯或就此提出申訴。
驗證類別範本由 2024 年 7 月 1 日起在印度開放。
在借助由 Meta 代管的雲端 API 或內部部署 API 傳送訊息範本時會用到範本。雲端 API 會使用機器學習技術審查範本和變數參數,以保護雲端 API 服務的安全性和完整性。雲端 API 審查範本和變數文字時,不會與 WhatsApp 分享任何資料。
您可以使用 Business Management API 或 WhatsApp Business 管理工具建立範本。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" } ] }
如要使用訊息範本來傳送訊息,則須使用訊息範本命名空間。
如要取得範本的命名空間,請向 /{whatsapp-business-account-ID}
端點傳送 GET
要求並加入 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}"
成功的話,系統會傳回一個帶有 WhatsApp Business 帳戶編號和命名空間的 JSON 物件:
{ "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 }