{"id":742,"date":"2026-10-29T13:21:12","date_gmt":"2026-10-29T13:21:12","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/send-whatsapp-template-message-api\/"},"modified":"2026-10-29T13:21:20","modified_gmt":"2026-10-29T13:21:20","slug":"send-whatsapp-template-message-api","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/en\/send-whatsapp-template-message-api\/","title":{"rendered":"How to send a WhatsApp template message via API: variables, media headers and buttons (full JSON)"},"content":{"rendered":"\n

Updated on October 29, 2026<\/em><\/p>\n\n\n\n

To send a template message with the WhatsApp Business API, make a POST<\/code> to \/{phone-number-id}\/messages<\/code> with \"type\": \"template\"<\/code>, the exact name<\/code> of an approved template, the language.code<\/code> it was created in, and a components<\/code> array holding the values for the header, body and button variables. You never send the template’s fixed text: you only send the parameters, and they must match the approved template in count, format and order.<\/p>\n\n\n\n

This guide gives you a ready-to-use payload for every case: text-only templates with positional and named variables, image, video and document headers (by link<\/code> and by id<\/code>), dynamic URL buttons, quick replies with a custom payload<\/code>, coupon codes, and a combined example. At the end you’ll find the most common parameter errors and how to send the same request through Vectalk.<\/p>\n\n\n\n

Anatomy of a template send request<\/h2>\n\n\n\n

Template messages use the same Cloud API<\/a> endpoint as every other message:<\/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
The body always has the same shell:<\/p>\n\n\n\n
{\n  \"messaging_product\": \"whatsapp\",\n  \"recipient_type\": \"individual\",\n  \"to\": \"16505551234\",\n  \"type\": \"template\",\n  \"template\": {\n    \"name\": \"template_name\",\n    \"language\": { \"code\": \"en_US\" },\n    \"components\": []\n  }\n}<\/code><\/pre>\n\n\n\n
Inside components<\/code>, each object has a type<\/code> that points to one part of the template:<\/p>\n\n\n\n
Component type<\/code><\/th>When to include it<\/th>What goes in parameters<\/code><\/th><\/tr><\/thead>
header<\/code><\/td>Header with a text variable or media<\/td>text<\/code>, image<\/code>, video<\/code>, document<\/code> or location<\/code><\/td><\/tr>
body<\/code><\/td>Body with variables<\/td>text<\/code> (also currency<\/code> and date_time<\/code>)<\/td><\/tr>
button<\/code><\/td>Button with a dynamic value<\/td>Depends on sub_type<\/code>: url<\/code>, quick_reply<\/code>, copy_code<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
If the template has no variables at all, you can leave components<\/code> out. The footer never appears in the send request because it doesn’t support variables. If you haven’t sent any message through the API yet, start with how to send a WhatsApp message via API with cURL, Node.js and Python<\/a>.<\/p>\n\n\n\n
1. Text template with positional variables<\/h2>\n\n\n\n
This is the default format: unless a different format was chosen at creation, the template uses positional variables, {{1}}<\/code>, {{2}}<\/code> and so on. According to Meta’s template documentation<\/a>, the values must be sent in the same order<\/strong> the placeholders appear in the text.<\/p>\n\n\n\n
Approved template (body):<\/p>\n\n\n\n
Hi {{1}}! Your order {{2}} is confirmed and will arrive in {{3}} business days.<\/code><\/pre>\n\n\n\n
Send request:<\/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\": \"16505551234\",\n    \"type\": \"template\",\n    \"template\": {\n      \"name\": \"order_confirmed\",\n      \"language\": { \"code\": \"en_US\" },\n      \"components\": [\n        {\n          \"type\": \"body\",\n          \"parameters\": [\n            { \"type\": \"text\", \"text\": \"Jessica\" },\n            { \"type\": \"text\", \"text\": \"#48213\" },\n            { \"type\": \"text\", \"text\": \"3\" }\n          ]\n        }\n      ]\n    }\n  }'<\/code><\/pre>\n\n\n\n
Three placeholders, three text<\/code> objects, in order. One missing, one extra or the wrong type, and the send fails (see the error table below).<\/p>\n\n\n\n
2. Template with named variables (parameter_name<\/code>)<\/h2>\n\n\n\n
At creation, a template can declare \"parameter_format\": \"named\"<\/code>. Variables then become names like {{first_name}}<\/code>, which must be unique and use only lowercase letters and underscores. When sending, each parameter carries a parameter_name<\/code> and, according to Meta, order no longer matters<\/strong>.<\/p>\n\n\n\n
Approved template (body):<\/p>\n\n\n\n
Thank you, {{first_name}}! Your order number is {{order_number}}.<\/code><\/pre>\n\n\n\n
Send request:<\/p>\n\n\n\n
{\n  \"messaging_product\": \"whatsapp\",\n  \"recipient_type\": \"individual\",\n  \"to\": \"16505551234\",\n  \"type\": \"template\",\n  \"template\": {\n    \"name\": \"order_confirmation\",\n    \"language\": { \"code\": \"en_US\" },\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\": \"Jessica\" }\n        ]\n      }\n    ]\n  }\n}<\/code><\/pre>\n\n\n\n
Named variables make your code easier to read and prevent the classic bug of swapping two values. The format is set at creation, not at send time: sending parameter_name<\/code> to a positional template (or the other way around) is a parameter error. How to set the format when creating the template is covered in how to create, edit and delete templates via the API<\/a>.<\/p>\n\n\n\n
Currency and date variables<\/h3>\n\n\n\n
Besides text<\/code>, the body accepts currency<\/code> parameters (with fallback_value<\/code>, code<\/code> and amount_1000<\/code>, the amount multiplied by 1,000) and date_time<\/code> parameters (with fallback_value<\/code>), as shown on the template media page<\/a>. Sending the value already formatted as text<\/code> also works.<\/p>\n\n\n\n
3. Media headers: image, video or document<\/h2>\n\n\n\n
If the template was approved with a media header, the send request must<\/strong> include the media in a header<\/code> component. The sample image you uploaded at creation is only used for review; it is never delivered to the customer. The parameter type<\/code> is image<\/code>, video<\/code> or document<\/code>, and the object with the same name accepts either link<\/code> or id<\/code>:<\/p>\n\n\n\n
Option<\/th>How it works<\/th>When to use it<\/th><\/tr><\/thead>
link<\/code><\/td>Public HTTPS URL of the file on your server<\/td>Files that change per message (invoices, tickets)<\/td><\/tr>
id<\/code><\/td>Media ID returned when you upload to Meta’s servers<\/td>The same media for many recipients (campaigns)<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Meta recommends id<\/code> to reduce errors and requests to your server, and warns that a link<\/code> must be on a publicly accessible server or the message will fail. When you use link<\/code>, the Cloud API caches the file for 10 minutes and reuses it if the same URL shows up again in that window; to force a fresh download, append a random query string to the URL, per the send messages documentation<\/a>.<\/p>\n\n\n\n
Image by link<\/h3>\n\n\n\n
{\n  \"messaging_product\": \"whatsapp\",\n  \"to\": \"16505551234\",\n  \"type\": \"template\",\n  \"template\": {\n    \"name\": \"promo_image\",\n    \"language\": { \"code\": \"en_US\" },\n    \"components\": [\n      {\n        \"type\": \"header\",\n        \"parameters\": [\n          { \"type\": \"image\", \"image\": { \"link\": \"https:\/\/cdn.example.com\/promo\/october.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
Document (PDF) by media ID<\/h3>\n\n\n\n
{\n  \"messaging_product\": \"whatsapp\",\n  \"to\": \"16505551234\",\n  \"type\": \"template\",\n  \"template\": {\n    \"name\": \"invoice_ready\",\n    \"language\": { \"code\": \"en_US\" },\n    \"components\": [\n      {\n        \"type\": \"header\",\n        \"parameters\": [\n          {\n            \"type\": \"document\",\n            \"document\": { \"id\": \"1013859600285441\", \"filename\": \"invoice-october.pdf\" }\n          }\n        ]\n      },\n      {\n        \"type\": \"body\",\n        \"parameters\": [\n          { \"type\": \"text\", \"text\": \"Carlos\" },\n          { \"type\": \"text\", \"text\": \"11\/10\/2026\" }\n        ]\n      }\n    ]\n  }\n}<\/code><\/pre>\n\n\n\n
filename<\/code> is optional and comes from the document object used in document messages<\/a>: the WhatsApp app uses the extension to show the right file icon. In Brazil, this pattern is common for sending a boleto<\/em> (a bank payment slip) as a PDF header.<\/p>\n\n\n\n
For video, the structure is the same: \"type\": \"video\"<\/code> and a video<\/code> object with link<\/code> or id<\/code>.<\/p>\n\n\n\n
To get a media ID, upload the file with POST \/{PHONE_NUMBER_ID}\/media<\/code>. Size limits, supported formats and the upload walkthrough are in how to send images, PDFs, audio and video via the WhatsApp API<\/a>.<\/p>\n\n\n\n
4. Dynamic URL button<\/h2>\n\n\n\n
A URL button can have one<\/strong> variable, always at the end of the URL. At creation, something like https:\/\/shop.example.com\/order\/{{1}}<\/code>. At send time, you only pass the suffix:<\/p>\n\n\n\n
{\n  \"messaging_product\": \"whatsapp\",\n  \"to\": \"16505551234\",\n  \"type\": \"template\",\n  \"template\": {\n    \"name\": \"order_tracking\",\n    \"language\": { \"code\": \"en_US\" },\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
Three rules that break a lot of integrations:<\/p>\n\n\n\n