身份验证模板
自 2024 年 4 月 1 日起,如果现有身份验证模板不是带有一次性密码按钮的身份验证模板,您均无法发送或编辑该模板,也无法对其进行申诉。
身份验证模板将于 2024 年 7 月 1 日在印度开放。
在使用由 Meta 托管的云端 API 或本地 API 发送模板消息时,您会用到模板。云端 API 借助机器学习审核模板和变量参数,以保护云端 API 服务的安全和诚信。在审核模板和变量文本时,云端 API 不会与 WhatsApp 分享任何信息。
您可以使用 WhatsApp Business 管理 API 或 WhatsApp 商务管理平台创建模板。WhatsApp Business 商业帐号可以拥有的模板数量由该帐号的母公司决定。如果母公司未经认证,则其下每个 WhatsApp Business 商业帐号最多可拥有 250 个模板。但是,如果母公司已经过认证,且至少有一个 WhatsApp Business 商业帐号具有商业电话号码和经批准的显示名,则每个 WhatsApp Business 商业帐号最多可拥有 6,000 个模板。
您需要提供:
在创建模板时,您可以添加特定语言的消息模板。这些模板会计入您的模板数限额。各消息模板所提供的翻译语言应保持一致。有关详情,请参阅帮助中心文章为什么我会在回调中看见“structure unavailable”错误?。
向 WhatsApp Business 商业帐号 > 消息模板端点发送 POST 请求,以创建模板。
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
,这会触发消息模板状态更新 Webhooks,其中包含 reason
(设为 INCORRECT_CATEGORY
)。建议您留意该 Webhooks,以便确定被拒的模板;或在新建模板上请求获取 rejected_reason
字段,该字段值将为 TAG_CONTENT_MISMATCH
。在这两种情况下,返回的 API 响应中都将包含模板的初始状态。
在类别验证过程中,如果您的模板状态已设为 REJECTED
,您有以下几个选择:
您可以在请求中加入 allow_category_change
属性,以便我们根据该模板的内容和模板分类指南对该模板进行自动分类。这可以防止模板状态因分类错误而被立即设为 REJECTED
。
请注意,仅在创建模板时才能进行自动分类。
状态为 PENDING
的模板将进入模板审核流程。我们会对每个新建或编辑的模板进行内容审核,以确保其内容符合我们的内容指南和政策。我们会根据审核结果,自动将模板状态更改为 APPROVED
或 REJECTED
,这会触发消息模板状态更新 Webhooks。
根据类别验证和模板审核的结果,我们会将模板的 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" }
向 WhatsApp Business 商业帐号 > 消息模板端点发送 GET 请求,获取 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" }
向 WhatsApp 消息模板端点发送 POST 请求,以编辑模板。您还可以使用 WhatsApp 管理工具 > 帐号工具 > 消息模板面板,手动编辑模板。
APPROVED
、REJECTED
或 PAUSED
状态的模板。category
或 components
。category
。POST /<WHATSAPP_MESSAGE_TEMPLATE_ID>
{ "category": "<CATEGORY>", "components": [<COMPONENTS>] }
占位符 | 描述 | 示例值 |
---|---|---|
字符串 | 如果省略 components 属性,则为必要项。 模板类别。 |
|
数组 | 如果省略 category 属性,则为必要项。 模板组件对象数组。 | 请参阅下方请求示例(编辑组件)部分。 |
将模板正文文本由包含营销和交易相关内容更改为仅包含营销内容的请求示例。
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 天内送达此消息。30 天后,您会收到“structure unavailable”错误消息,且客户将收不到此模板消息。按名称删除模板会删除所有与此名称一致的模板(这意味着,同名但语言不同的模板也将被删除)。
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 }