{"id":741,"date":"2026-10-29T13:21:11","date_gmt":"2026-10-29T13:21:11","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/enviar-template-api-whatsapp\/"},"modified":"2026-10-29T13:21:18","modified_gmt":"2026-10-29T13:21:18","slug":"enviar-template-api-whatsapp","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/enviar-template-api-whatsapp\/","title":{"rendered":"Como enviar template pela API do WhatsApp: vari\u00e1veis, m\u00eddia no cabe\u00e7alho e bot\u00f5es (JSON completo)"},"content":{"rendered":"\n

Atualizado em 29\/10\/2026<\/em><\/p>\n\n\n\n

Para enviar um template pela API do WhatsApp, fa\u00e7a um POST<\/code> em \/{phone-number-id}\/messages<\/code> com \"type\": \"template\"<\/code>, o name<\/code> exato do template aprovado, o language.code<\/code> em que ele foi criado e um array components<\/code> com os valores das vari\u00e1veis do cabe\u00e7alho, do corpo e dos bot\u00f5es. O texto fixo n\u00e3o vai no envio: voc\u00ea manda s\u00f3 os par\u00e2metros, e eles precisam bater em quantidade, formato e ordem com o que foi aprovado.<\/p>\n\n\n\n

Este guia traz um payload pronto para cada caso: s\u00f3 texto com vari\u00e1veis posicionais e nomeadas, cabe\u00e7alho com imagem, v\u00eddeo ou documento (por link<\/code> e por id<\/code>), bot\u00e3o de URL din\u00e2mica, quick reply com payload<\/code>, c\u00f3digo de cupom e um exemplo combinado. No fim, a tabela de erros de par\u00e2metro mais comuns e como fazer o mesmo envio pela Vectalk.<\/p>\n\n\n\n

Anatomia de um envio de template<\/h2>\n\n\n\n

Todo envio de template usa o mesmo endpoint da Cloud API<\/a> que as outras mensagens:<\/p>\n\n\n\n

POST https:\/\/graph.facebook.com\/v26.0\/{PHONE_NUMBER_ID}\/messages\nAuthorization: Bearer {ACCESS_TOKEN}\nContent-Type: application\/json<\/code><\/pre>\n\n\n\n
O corpo tem sempre a mesma casca:<\/p>\n\n\n\n
{\n  \"messaging_product\": \"whatsapp\",\n  \"recipient_type\": \"individual\",\n  \"to\": \"5511999999999\",\n  \"type\": \"template\",\n  \"template\": {\n    \"name\": \"nome_do_template\",\n    \"language\": { \"code\": \"pt_BR\" },\n    \"components\": []\n  }\n}<\/code><\/pre>\n\n\n\n
Dentro de components<\/code>, cada objeto tem um type<\/code> que aponta para uma parte do template:<\/p>\n\n\n\n
type<\/code> do componente<\/th>Quando incluir<\/th>O que vai em parameters<\/code><\/th><\/tr><\/thead>
header<\/code><\/td>Cabe\u00e7alho com vari\u00e1vel de texto ou com m\u00eddia<\/td>text<\/code>, image<\/code>, video<\/code>, document<\/code> ou location<\/code><\/td><\/tr>
body<\/code><\/td>Corpo com vari\u00e1veis<\/td>text<\/code> (e tamb\u00e9m currency<\/code> e date_time<\/code>)<\/td><\/tr>
button<\/code><\/td>Bot\u00e3o com valor din\u00e2mico<\/td>Depende do sub_type<\/code>: url<\/code>, quick_reply<\/code>, copy_code<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Se o template n\u00e3o tem vari\u00e1vel nenhuma, components<\/code> pode ficar de fora. O rodap\u00e9 (footer<\/code>) nunca aparece no envio, porque n\u00e3o aceita vari\u00e1veis. Se voc\u00ea est\u00e1 come\u00e7ando e ainda n\u00e3o mandou nenhuma mensagem pela API, veja antes como enviar mensagem pela API do WhatsApp com cURL, Node.js e Python<\/a>.<\/p>\n\n\n\n
1. Template s\u00f3 texto com vari\u00e1veis posicionais<\/h2>\n\n\n\n
\u00c9 o formato padr\u00e3o: se ningu\u00e9m escolheu outro formato na cria\u00e7\u00e3o, o template usa vari\u00e1veis posicionais, {{1}}<\/code>, {{2}}<\/code> e assim por diante. Segundo a documenta\u00e7\u00e3o de templates da Meta<\/a>, os valores precisam vir na mesma ordem<\/strong> em que os placeholders aparecem no texto.<\/p>\n\n\n\n
Template aprovado (corpo):<\/p>\n\n\n\n
Ol\u00e1 {{1}}! Seu pedido {{2}} foi confirmado e chega em {{3}} dias \u00fateis.<\/code><\/pre>\n\n\n\n
Envio:<\/p>\n\n\n\n
curl -X POST \"https:\/\/graph.facebook.com\/v26.0\/$PHONE_NUMBER_ID\/messages\" \\\n  -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\n    \"messaging_product\": \"whatsapp\",\n    \"recipient_type\": \"individual\",\n    \"to\": \"5511999999999\",\n    \"type\": \"template\",\n    \"template\": {\n      \"name\": \"pedido_confirmado\",\n      \"language\": { \"code\": \"pt_BR\" },\n      \"components\": [\n        {\n          \"type\": \"body\",\n          \"parameters\": [\n            { \"type\": \"text\", \"text\": \"Mariana\" },\n            { \"type\": \"text\", \"text\": \"#48213\" },\n            { \"type\": \"text\", \"text\": \"3\" }\n          ]\n        }\n      ]\n    }\n  }'<\/code><\/pre>\n\n\n\n
Tr\u00eas placeholders, tr\u00eas objetos text<\/code>, na ordem. Faltou um, sobrou um ou trocou o tipo: o envio falha (veja a tabela de erros mais abaixo).<\/p>\n\n\n\n
2. Template com vari\u00e1veis nomeadas (parameter_name<\/code>)<\/h2>\n\n\n\n
Na cria\u00e7\u00e3o, o template pode declarar \"parameter_format\": \"named\"<\/code>. A\u00ed as vari\u00e1veis viram nomes como {{first_name}}<\/code>, que precisam ser \u00fanicos e usar s\u00f3 letras min\u00fasculas e sublinhado. No envio, cada par\u00e2metro leva um parameter_name<\/code> e, segundo a Meta, a ordem deixa de importar<\/strong>.<\/p>\n\n\n\n
Template aprovado (corpo):<\/p>\n\n\n\n
Obrigado, {{first_name}}! O n\u00famero do seu pedido \u00e9 {{order_number}}.<\/code><\/pre>\n\n\n\n
Envio:<\/p>\n\n\n\n
{\n  \"messaging_product\": \"whatsapp\",\n  \"recipient_type\": \"individual\",\n  \"to\": \"5511999999999\",\n  \"type\": \"template\",\n  \"template\": {\n    \"name\": \"confirmacao_pedido\",\n    \"language\": { \"code\": \"pt_BR\" },\n    \"components\": [\n      {\n        \"type\": \"body\",\n        \"parameters\": [\n          { \"type\": \"text\", \"parameter_name\": \"order_number\", \"text\": \"SKBUP2-4CPIG9\" },\n          { \"type\": \"text\", \"parameter_name\": \"first_name\", \"text\": \"J\u00e9ssica\" }\n        ]\n      }\n    ]\n  }\n}<\/code><\/pre>\n\n\n\n
Vari\u00e1veis nomeadas deixam o c\u00f3digo mais leg\u00edvel e evitam o erro cl\u00e1ssico de trocar a ordem de dois valores. O formato \u00e9 definido na cria\u00e7\u00e3o e n\u00e3o no envio: mandar parameter_name<\/code> para um template posicional (ou o contr\u00e1rio) \u00e9 um erro de par\u00e2metro. Como definir o formato na cria\u00e7\u00e3o est\u00e1 no guia de criar, editar e excluir templates pela API<\/a>.<\/p>\n\n\n\n
Vari\u00e1veis de moeda e data<\/h3>\n\n\n\n
Al\u00e9m de text<\/code>, o corpo aceita par\u00e2metros currency<\/code> (com fallback_value<\/code>, code<\/code> e amount_1000<\/code>, o valor multiplicado por 1.000) e date_time<\/code> (com fallback_value<\/code>), como mostra a p\u00e1gina de m\u00eddia em templates<\/a>. Mandar o valor j\u00e1 formatado como text<\/code> tamb\u00e9m funciona.<\/p>\n\n\n\n
3. Cabe\u00e7alho com imagem, v\u00eddeo ou documento<\/h2>\n\n\n\n
Se o template foi aprovado com cabe\u00e7alho de m\u00eddia, o envio precisa<\/strong> trazer a m\u00eddia em um componente header<\/code>. A imagem de exemplo usada na cria\u00e7\u00e3o serve s\u00f3 para a revis\u00e3o; ela n\u00e3o \u00e9 enviada ao cliente. O type<\/code> do par\u00e2metro \u00e9 image<\/code>, video<\/code> ou document<\/code>, e o objeto com o mesmo nome aceita link<\/code> ou id<\/code>:<\/p>\n\n\n\n
Op\u00e7\u00e3o<\/th>Como funciona<\/th>Quando usar<\/th><\/tr><\/thead>
link<\/code><\/td>URL HTTPS p\u00fablica do arquivo no seu servidor<\/td>Arquivos que mudam a cada envio (boleto, nota fiscal)<\/td><\/tr>
id<\/code><\/td>Media ID obtido no upload para os servidores da Meta<\/td>Mesma m\u00eddia para muitos destinat\u00e1rios (campanha)<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
A Meta recomenda id<\/code>, para reduzir erros e chamadas ao seu servidor, e avisa que o link<\/code> precisa estar em servidor p\u00fablico, sen\u00e3o a mensagem falha. Quando voc\u00ea usa link<\/code>, a Cloud API guarda o arquivo em cache por 10 minutos e reaproveita se a mesma URL aparecer de novo nesse intervalo; para for\u00e7ar outro download, acrescente uma query string aleat\u00f3ria \u00e0 URL, conforme a documenta\u00e7\u00e3o de envio<\/a>.<\/p>\n\n\n\n
Imagem por link<\/h3>\n\n\n\n
{\n  \"messaging_product\": \"whatsapp\",\n  \"to\": \"5511999999999\",\n  \"type\": \"template\",\n  \"template\": {\n    \"name\": \"promo_imagem\",\n    \"language\": { \"code\": \"pt_BR\" },\n    \"components\": [\n      {\n        \"type\": \"header\",\n        \"parameters\": [\n          { \"type\": \"image\", \"image\": { \"link\": \"https:\/\/cdn.minhaloja.com.br\/promo\/outubro.jpg\" } }\n        ]\n      },\n      {\n        \"type\": \"body\",\n        \"parameters\": [\n          { \"type\": \"text\", \"text\": \"20%\" }\n        ]\n      }\n    ]\n  }\n}<\/code><\/pre>\n\n\n\n
Documento (PDF) por media ID<\/h3>\n\n\n\n
{\n  \"messaging_product\": \"whatsapp\",\n  \"to\": \"5511999999999\",\n  \"type\": \"template\",\n  \"template\": {\n    \"name\": \"boleto_disponivel\",\n    \"language\": { \"code\": \"pt_BR\" },\n    \"components\": [\n      {\n        \"type\": \"header\",\n        \"parameters\": [\n          {\n            \"type\": \"document\",\n            \"document\": { \"id\": \"1013859600285441\", \"filename\": \"boleto-outubro.pdf\" }\n          }\n        ]\n      },\n      {\n        \"type\": \"body\",\n        \"parameters\": [\n          { \"type\": \"text\", \"text\": \"Carlos\" },\n          { \"type\": \"text\", \"text\": \"10\/11\/2026\" }\n        ]\n      }\n    ]\n  }\n}<\/code><\/pre>\n\n\n\n
O filename<\/code> \u00e9 opcional e vem do objeto de documento das mensagens de documento<\/a>: o app usa a extens\u00e3o para mostrar o \u00edcone certo.<\/p>\n\n\n\n
Para v\u00eddeo, a estrutura \u00e9 a mesma: \"type\": \"video\"<\/code> e um objeto video<\/code> com link<\/code> ou id<\/code>.<\/p>\n\n\n\n
Para gerar o media ID, fa\u00e7a o upload em POST \/{PHONE_NUMBER_ID}\/media<\/code>. Limites de tamanho, formatos aceitos e o passo a passo do upload est\u00e3o em como enviar imagem, PDF, \u00e1udio e v\u00eddeo pela API do WhatsApp<\/a>.<\/p>\n\n\n\n
4. Bot\u00e3o de URL din\u00e2mica<\/h2>\n\n\n\n
Um bot\u00e3o de URL pode ter uma<\/strong> vari\u00e1vel, sempre no fim da URL. Na cria\u00e7\u00e3o, algo como https:\/\/minhaloja.com.br\/pedido\/{{1}}<\/code>. No envio, voc\u00ea manda s\u00f3 o sufixo:<\/p>\n\n\n\n
{\n  \"messaging_product\": \"whatsapp\",\n  \"to\": \"5511999999999\",\n  \"type\": \"template\",\n  \"template\": {\n    \"name\": \"rastreio_pedido\",\n    \"language\": { \"code\": \"pt_BR\" },\n    \"components\": [\n      {\n        \"type\": \"body\",\n        \"parameters\": [\n          { \"type\": \"text\", \"text\": \"#48213\" }\n        ]\n      },\n      {\n        \"type\": \"button\",\n        \"sub_type\": \"url\",\n        \"index\": \"0\",\n        \"parameters\": [\n          { \"type\": \"text\", \"text\": \"48213?utm_source=whatsapp\" }\n        ]\n      }\n    ]\n  }\n}<\/code><\/pre>\n\n\n\n
Tr\u00eas regras que derrubam muita integra\u00e7\u00e3o:<\/p>\n\n\n\n