通过 API 管理模板 - WhatsApp Cloud API通过 WhatsApp Business Management API 以编程方式创建、列出、删除和管理消息模板的完整指南。目录概述模板类别创建模板列出模板删除模板带变量的模板带媒体的模板带按钮的模板发送模板消息最佳实践概述模板是 WhatsApp 预先批准的消息。它们是开始与客户对话的唯一方式24 小时窗口外。限制每个 WABA 账号最多 6,000 个模板翻译批准需要几分钟到几小时模板提交后无法编辑删除并重新创建模板正文最多 1,600 个字符基础端点https://graph.facebook.com/v21.0/{waba-id}/message_templates模板类别类别用途费用MARKETING促销、活动、发布$0.025-$0.1365/条UTILITY订单确认、更新、跟踪$0.004-$0.0456/条AUTHENTICATIONOTP、密码重置、两步验证$0.004-$0.0456/条类别影响费用和批准规则。营销模板有更严格的规则。创建模板Node.jsinterfaceTemplateComponent{type:HEADER|BODY|FOOTER|BUTTONS;format?:TEXT|IMAGE|VIDEO|DOCUMENT;text?:string;example?:{header_handle?:string[];body_text?:string[][]};buttons?:Array{type:QUICK_REPLY|URL|PHONE_NUMBER;text:string;url?:string;phone_number?:string;example?:string[];};}asyncfunctioncreateTemplate(name:string,category:MARKETING|UTILITY|AUTHENTICATION,language:string,components:TemplateComponent[]):Promiseany{constresponseawaitaxios.post(${GRAPH_API}/${process.env.WABA_ID}/message_templates,{name,category,language,components},{headers:{Authorization:Bearer${process.env.WHATSAPP_TOKEN}}});returnresponse.data;// { id: template_id, status: PENDING, category: UTILITY }}// Exemplo: Criar template de confirmacao de pedidoawaitcreateTemplate(order_confirmation_v1,UTILITY,pt_BR,[{type:HEADER,format:TEXT,text:Pedido Confirmado!},{type:BODY,text:Ola {{1}}, seu pedido #{{2}} foi confirmado!\n\nValor: R$ {{3}}\nPrevisao de entrega: {{4}},example:{body_text:[[Joao,12345,99,90,3 dias uteis]]}},{type:FOOTER,text:Obrigado por comprar conosco!}]);Pythonasyncdefcreate_template(name:str,category:str,language:str,components:list[dict])-dict:asyncwithhttpx.AsyncClient()asclient:responseawaitclient.post(f{GRAPH_API}/{os.environ[WABA_ID]}/message_templates,json{name:name,category:category,language:language,components:components},headers{Authorization:fBearer{os.environ[WHATSAPP_TOKEN]}})returnresponse.json()# Exemplo: Criar template de boas-vindasawaitcreate_template(namewelcome_v1,categoryMARKETING,languagept_BR,components[{type:BODY,text:Ola {{1}}, bem-vindo a nossa loja! \n\nConfira nossas ofertas exclusivas.,example:{body_text:[[Maria]]}},{type:BUTTONS,buttons:[{type:URL,text:Ver Ofertas,url:https://example.com/ofertas},{type:QUICK_REPLY,text:Falar com Vendedor}]}])列出模板Node.jsasyncfunctionlistTemplates(status?:string):Promiseany[]{constparamsnewURLSearchParams({limit:100});if(status)params.append(status,status);constresponseawaitaxios.get(${GRAPH_API}/${process.env.WABA_ID}/message_templates?${params},{headers:{Authorization:Bearer${process.env.WHATSAPP_TOKEN}}});returnresponse.data.data;}// Listar apenas templates aprovadosconstapprovedawaitlistTemplates(APPROVED);// Listar todosconstallawaitlistTemplates();Pythonasyncdeflist_templates(status:str|NoneNone)-list[dict]:params{limit:100}ifstatus:params[status]statusasyncwithhttpx.AsyncClient()asclient:responseawaitclient.get(f{GRAPH_API}/{os.environ[WABA_ID]}/message_templates,paramsparams,headers{Authorization:fBearer{os.environ[WHATSAPP_TOKEN]}})returnresponse.json()[data]模板状态状态含义APPROVED已批准可随时使用PENDINGWhatsApp 正在审核REJECTED已拒绝在响应中查看原因PAUSED因质量低而暂停DISABLED已禁用删除模板Node.jsasyncfunctiondeleteTemplate(templateName:string):Promisevoid{awaitaxios.delete(${GRAPH_API}/${process.env.WABA_ID}/message_templates,{data:{name:templateName},headers:{Authorization:Bearer${process.env.WHATSAPP_TOKEN}}});}awaitdeleteTemplate(old_template_v1);Pythonasyncdefdelete_template(template_name:str)-None:asyncwithhttpx.AsyncClient()asclient:awaitclient.request(DELETE,f{GRAPH_API}/{os.environ[WABA_ID]}/message_templates,json{name:template_name},headers{Authorization:fBearer{os.environ[WHATSAPP_TOKEN]}})注意删除模板会移除所有关联的翻译。带变量的模板变量在模板文本中用{{N}}从 1 开始表示。规则变量必须连续{{1}}、{{2}}、{{3}}创建时提供带示例值的example发送时提供带实际值的parameters不要跳过数字{{1}}、{{3}}而没有{{2}}是无效的完整示例创建{type:BODY,text:Ola {{1}}, seu pedido #{{2}} sera entregue em {{3}}.,example:{body_text:[[Joao,12345,2 dias]]}}发送{type:body,parameters:[{type:text,text:Maria},{type:text,text:67890},{type:text,text:3 dias uteis}]}带媒体的模板带图片的标题创建{type:HEADER,format:IMAGE,example:{header_handle:[4::aW1hZ2UvanBlZw:ARb...]}}要获取header_handle先上传示例图片POST /{app-id}/uploads?file_typeimage/jpegfile_length12345发送{type:header,parameters:[{type:image,image:{link:https://example.com/image.jpg}}]}带文档的标题创建{type:HEADER,format:DOCUMENT,example:{header_handle:[4::YXBwbGljYXRpb24vcGRm:ARb...]}}发送{type:header,parameters:[{type:document,document:{link:https://example.com/invoice.pdf,filename:Nota_Fiscal_12345.pdf}}]}带按钮的模板快速回复最多 3 个按钮{type:BUTTONS,buttons:[{type:QUICK_REPLY,text:Sim, confirmo},{type:QUICK_REPLY,text:Nao, cancelar},{type:QUICK_REPLY,text:Falar com atendente}]}URL 按钮{type:BUTTONS,buttons:[{type:URL,text:Rastrear Pedido,url:https://example.com/tracking/{{1}},example:[12345]}]}电话号码按钮{type:BUTTONS,buttons:[{type:PHONE_NUMBER,text:Ligar para Suporte,phone_number:5511999999999}]}发送带动态 URL 按钮的模板awaitsendMessage({messaging_product:whatsapp,to:5511999999999,type:template,template:{name:order_tracking_v1,language:{code:pt_BR},components:[{type:body,parameters:[{type:text,text:Maria},{type:text,text:67890}]},{type:button,sub_type:url,index:0,parameters:[{type:text,text:67890}// substitui {{1}} na URL]}]}});发送模板消息完整示例 - Node.jsasyncfunctionsendTemplate(to:string,templateName:string,language:string,components?:Array{type:string;parameters?:Array{type:string;text?:string;image?:any;document?:any};sub_type?:string;index?:number;}):Promiseany{constpayload:any{messaging_product:whatsapp,to,type:template,template:{name:templateName,language:{code:language}}};if(components){payload.template.componentscomponents;}returnsendWithRetry(payload);}// Uso simples (sem variaveis)awaitsendTemplate(5511999999999,hello_world,pt_BR);// Com variaveis no bodyawaitsendTemplate(5511999999999,order_confirmation_v1,pt_BR,[{type:body,parameters:[{type:text,text:Joao},{type:text,text:12345},{type:text,text:99,90},{type:text,text:3 dias uteis}]}]);完整示例 - Pythonasyncdefsend_template(to:str,template_name:str,language:str,components:list[dict]|NoneNone)-dict:payload{messaging_product:whatsapp,to:to,type:template,template:{name:template_name,language:{code:language}}}ifcomponents:payload[template][components]componentsreturnawaitsend_with_retry(payload)# Uso simplesawaitsend_template(5511999999999,hello_world,pt_BR)# Com variaveisawaitsend_template(5511999999999,order_confirmation_v1,pt_BR,[{type:body,parameters:[{type:text,text:Maria},{type:text,text:67890},{type:text,text:149,90},{type:text,text:5 dias uteis}]}])最佳实践命名为模板名称使用一致的命名模式{finalidade}_{descricao}_v{versao}示例order_confirmation_v1welcome_new_customer_v2payment_reminder_v1nps_survey_v3版本管理由于模板无法编辑创建新版本template_name_v2测试新版本批准后迁移代码以使用 v2不再需要时删除 v1批准技巧在正文中避免过度促销的语言在example中包含清晰真实的示例不要使用短链接bit.ly 等不要包含可能被解读为垃圾邮件的内容实用模板比营销模板批准更快使用变量进行个性化客户姓名、订单号监控// Verificar status de templates periodicamenteasyncfunctionmonitorTemplates():Promisevoid{consttemplatesawaitlistTemplates();for(consttemplateoftemplates){if(template.statusREJECTED){console.warn(Template rejeitado:${template.name});console.warn(Motivo:${template.rejected_reason});}if(template.statusPAUSED){console.warn(Template pausado por qualidade:${template.name});}}}