{"id":743,"date":"2026-10-29T13:21:12","date_gmt":"2026-10-29T13:21:12","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/enviar-plantilla-api-whatsapp\/"},"modified":"2026-10-29T13:21:41","modified_gmt":"2026-10-29T13:21:41","slug":"enviar-plantilla-api-whatsapp","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/es\/enviar-plantilla-api-whatsapp\/","title":{"rendered":"C\u00f3mo enviar una plantilla por la API de WhatsApp: variables, multimedia en el encabezado y botones (JSON completo)"},"content":{"rendered":"\n

Actualizado el 29\/10\/2026<\/em><\/p>\n\n\n\n

Para enviar una plantilla (template) por la API de WhatsApp, haz un POST<\/code> a \/{phone-number-id}\/messages<\/code> con \"type\": \"template\"<\/code>, el name<\/code> exacto de la plantilla aprobada, el language.code<\/code> con el que se cre\u00f3 y un arreglo components<\/code> con los valores de las variables del encabezado, del cuerpo y de los botones. El texto fijo no se env\u00eda: solo mandas los par\u00e1metros, y deben coincidir en cantidad, formato y orden con lo aprobado.<\/p>\n\n\n\n

Esta gu\u00eda trae un payload listo para cada caso: solo texto con variables posicionales y nombradas, encabezado con imagen, video o documento (por link<\/code> y por id<\/code>), bot\u00f3n de URL din\u00e1mica, respuesta r\u00e1pida con payload<\/code>, c\u00f3digo de cup\u00f3n y un ejemplo combinado. Al final, la tabla de errores de par\u00e1metros m\u00e1s comunes y c\u00f3mo hacer el mismo env\u00edo con Vectalk.<\/p>\n\n\n\n

Anatom\u00eda de un env\u00edo de plantilla<\/h2>\n\n\n\n

Las plantillas usan el mismo endpoint de la Cloud API<\/a> que los dem\u00e1s mensajes:<\/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
El cuerpo siempre tiene la misma estructura base:<\/p>\n\n\n\n
{\n  \"messaging_product\": \"whatsapp\",\n  \"recipient_type\": \"individual\",\n  \"to\": \"573001234567\",\n  \"type\": \"template\",\n  \"template\": {\n    \"name\": \"nombre_de_la_plantilla\",\n    \"language\": { \"code\": \"es_MX\" },\n    \"components\": []\n  }\n}<\/code><\/pre>\n\n\n\n
Dentro de components<\/code>, cada objeto tiene un type<\/code> que apunta a una parte de la plantilla:<\/p>\n\n\n\n
type<\/code> del componente<\/th>Cu\u00e1ndo incluirlo<\/th>Qu\u00e9 va en parameters<\/code><\/th><\/tr><\/thead>
header<\/code><\/td>Encabezado con variable de texto o multimedia<\/td>text<\/code>, image<\/code>, video<\/code>, document<\/code> o location<\/code><\/td><\/tr>
body<\/code><\/td>Cuerpo con variables<\/td>text<\/code> (y tambi\u00e9n currency<\/code> y date_time<\/code>)<\/td><\/tr>
button<\/code><\/td>Bot\u00f3n con valor din\u00e1mico<\/td>Depende del sub_type<\/code>: url<\/code>, quick_reply<\/code>, copy_code<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Si la plantilla no tiene ninguna variable, puedes omitir components<\/code>. El pie (footer<\/code>) nunca aparece en el env\u00edo, porque no admite variables. Si todav\u00eda no enviaste ning\u00fan mensaje por la API, empieza por c\u00f3mo enviar un mensaje por la API de WhatsApp con cURL, Node.js y Python<\/a>.<\/p>\n\n\n\n
1. Plantilla de texto con variables posicionales<\/h2>\n\n\n\n
Es el formato predeterminado: si nadie eligi\u00f3 otro formato al crearla, la plantilla usa variables posicionales, {{1}}<\/code>, {{2}}<\/code> y as\u00ed sucesivamente. Seg\u00fan la documentaci\u00f3n de plantillas de Meta<\/a>, los valores deben enviarse en el mismo orden<\/strong> en que aparecen los marcadores en el texto.<\/p>\n\n\n\n
Plantilla aprobada (cuerpo):<\/p>\n\n\n\n
\u00a1Hola {{1}}! Tu pedido {{2}} est\u00e1 confirmado y llega en {{3}} d\u00edas h\u00e1biles.<\/code><\/pre>\n\n\n\n
Env\u00edo:<\/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\": \"573001234567\",\n    \"type\": \"template\",\n    \"template\": {\n      \"name\": \"pedido_confirmado\",\n      \"language\": { \"code\": \"es_MX\" },\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
Tres marcadores, tres objetos text<\/code>, en orden. Si falta uno, sobra uno o cambia el tipo, el env\u00edo falla (mira la tabla de errores m\u00e1s abajo).<\/p>\n\n\n\n
2. Plantilla con variables nombradas (parameter_name<\/code>)<\/h2>\n\n\n\n
Al crearla, la plantilla puede declarar \"parameter_format\": \"named\"<\/code>. Las variables pasan a ser nombres como {{first_name}}<\/code>, que deben ser \u00fanicos y usar solo min\u00fasculas y guion bajo. En el env\u00edo, cada par\u00e1metro lleva un parameter_name<\/code> y, seg\u00fan Meta, el orden deja de importar<\/strong>.<\/p>\n\n\n\n
Plantilla aprobada (cuerpo):<\/p>\n\n\n\n
\u00a1Gracias, {{first_name}}! El n\u00famero de tu pedido es {{order_number}}.<\/code><\/pre>\n\n\n\n
Env\u00edo:<\/p>\n\n\n\n
{\n  \"messaging_product\": \"whatsapp\",\n  \"recipient_type\": \"individual\",\n  \"to\": \"573001234567\",\n  \"type\": \"template\",\n  \"template\": {\n    \"name\": \"confirmacion_pedido\",\n    \"language\": { \"code\": \"es_MX\" },\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
Las variables nombradas hacen el c\u00f3digo m\u00e1s legible y evitan el error cl\u00e1sico de invertir dos valores. El formato se define al crear la plantilla, no al enviarla: mandar parameter_name<\/code> a una plantilla posicional (o al rev\u00e9s) es un error de par\u00e1metro. C\u00f3mo definir el formato al crearla est\u00e1 en la gu\u00eda de crear, editar y eliminar plantillas por la API<\/a>.<\/p>\n\n\n\n
Variables de moneda y fecha<\/h3>\n\n\n\n
Adem\u00e1s de text<\/code>, el cuerpo acepta par\u00e1metros currency<\/code> (con fallback_value<\/code>, code<\/code> y amount_1000<\/code>, el monto multiplicado por 1.000) y date_time<\/code> (con fallback_value<\/code>), como muestra la p\u00e1gina de multimedia en plantillas<\/a>. Enviar el valor ya formateado como text<\/code> tambi\u00e9n funciona.<\/p>\n\n\n\n
3. Encabezado con imagen, video o documento<\/h2>\n\n\n\n
Si la plantilla se aprob\u00f3 con encabezado multimedia, el env\u00edo debe<\/strong> incluir el archivo en un componente header<\/code>. La imagen de ejemplo usada al crearla solo sirve para la revisi\u00f3n; no se le env\u00eda al cliente. El type<\/code> del par\u00e1metro es image<\/code>, video<\/code> o document<\/code>, y el objeto con el mismo nombre acepta link<\/code> o id<\/code>:<\/p>\n\n\n\n
Opci\u00f3n<\/th>C\u00f3mo funciona<\/th>Cu\u00e1ndo usarla<\/th><\/tr><\/thead>
link<\/code><\/td>URL HTTPS p\u00fablica del archivo en tu servidor<\/td>Archivos que cambian en cada env\u00edo (facturas, comprobantes)<\/td><\/tr>
id<\/code><\/td>Media ID obtenido al subir el archivo a los servidores de Meta<\/td>El mismo archivo para muchos destinatarios (campa\u00f1as)<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Meta recomienda id<\/code>, para reducir errores y solicitudes a tu servidor, y advierte que el link<\/code> debe estar en un servidor p\u00fablico o el mensaje fallar\u00e1. Cuando usas link<\/code>, la Cloud API guarda el archivo en cach\u00e9 por 10 minutos y lo reutiliza si la misma URL vuelve a aparecer en ese lapso; para forzar otra descarga, agrega una query string aleatoria a la URL, seg\u00fan la documentaci\u00f3n de env\u00edo<\/a>.<\/p>\n\n\n\n
Imagen por link<\/h3>\n\n\n\n
{\n  \"messaging_product\": \"whatsapp\",\n  \"to\": \"573001234567\",\n  \"type\": \"template\",\n  \"template\": {\n    \"name\": \"promo_imagen\",\n    \"language\": { \"code\": \"es_MX\" },\n    \"components\": [\n      {\n        \"type\": \"header\",\n        \"parameters\": [\n          { \"type\": \"image\", \"image\": { \"link\": \"https:\/\/cdn.mitienda.com\/promo\/octubre.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\": \"573001234567\",\n  \"type\": \"template\",\n  \"template\": {\n    \"name\": \"factura_disponible\",\n    \"language\": { \"code\": \"es_MX\" },\n    \"components\": [\n      {\n        \"type\": \"header\",\n        \"parameters\": [\n          {\n            \"type\": \"document\",\n            \"document\": { \"id\": \"1013859600285441\", \"filename\": \"factura-octubre.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
filename<\/code> es opcional y viene del objeto de documento de los mensajes de documento<\/a>: la app usa la extensi\u00f3n para mostrar el \u00edcono correcto. En Brasil, este patr\u00f3n es com\u00fan para enviar el boleto<\/em> (un comprobante bancario de pago) como PDF en el encabezado.<\/p>\n\n\n\n
Para video, la estructura es la misma: \"type\": \"video\"<\/code> y un objeto video<\/code> con link<\/code> o id<\/code>.<\/p>\n\n\n\n
Para obtener el media ID, sube el archivo con POST \/{PHONE_NUMBER_ID}\/media<\/code>. L\u00edmites de tama\u00f1o, formatos aceptados y el paso a paso de la subida est\u00e1n en c\u00f3mo enviar imagen, PDF, audio y video por la API de WhatsApp<\/a>.<\/p>\n\n\n\n
4. Bot\u00f3n de URL din\u00e1mica<\/h2>\n\n\n\n
Un bot\u00f3n de URL puede tener una<\/strong> variable, siempre al final de la URL. Al crearlo, algo como https:\/\/mitienda.com\/pedido\/{{1}}<\/code>. En el env\u00edo, solo mandas el sufijo:<\/p>\n\n\n\n
{\n  \"messaging_product\": \"whatsapp\",\n  \"to\": \"573001234567\",\n  \"type\": \"template\",\n  \"template\": {\n    \"name\": \"rastreo_pedido\",\n    \"language\": { \"code\": \"es_MX\" },\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
Tres reglas que rompen muchas integraciones:<\/p>\n\n\n\n