Cómo mandar una plantilla de WhatsApp con imagen y botón de URL por la API
La foto y el botón salen en el mismo POST /api/v2/messages. El header lleva image.link y el botón, sub_type url con solo el sufijo. No existe POST /api/v2/media.
Respuesta corta: una plantilla que ya está aprobada, con foto arriba y un botón de link, se manda con POST https://api.waspytech.com/api/v2/messages, type: "template". El encabezado va en un componente header con image.link. El botón dinámico va en un componente button, sub_type: "url", index en string y solo el sufijo de la URL. No existe POST /api/v2/media. El caso de variables de texto, sin foto, está en enviar una plantilla.
La referencia del POST está en messages y la guía de envío en send template. Lo que la v2 no sube está en limitaciones.
El POST
curl -sS -X POST https://api.waspytech.com/api/v2/messages \
-H "Authorization: Bearer $WASPY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pedido-1847-link" \
-d '{
"phoneNumberId": "UUID-DEL-CANAL",
"to": "+5491155554444",
"type": "template",
"clientRef": "pedido-1847",
"template": {
"name": "aviso_pago",
"language": { "code": "es_AR" },
"components": [
{
"type": "header",
"parameters": [
{ "type": "image", "image": { "link": "https://cdn.mitienda.com.ar/remito-1847.jpg" } }
]
},
{
"type": "body",
"parameters": [
{ "type": "text", "text": "Laura" },
{ "type": "text", "text": "1847" }
]
},
{
"type": "button",
"sub_type": "url",
"index": "0",
"parameters": [
{ "type": "text", "text": "1847/abc" }
]
}
]
}
}'
Scope messages:write. phoneNumberId es el UUID de data[].id en GET /api/v2/channels, no el id de teléfono de Meta. to va en E.164. La respuesta 201 trae status: "queued" y waMessageId: null.
Idempotency-Key (hasta 256 caracteres) guarda la respuesta 24 horas. Un reintento con la misma clave no manda otro WhatsApp. clientRef vuelve en cada webhook de estado.
Qué viaja a Meta y qué se queda en la bandeja
El POST puede mezclar la definición de la plantilla con los parámetros del envío. Antes de llamar a Meta, el worker se queda solo con esto:
| Componente | ¿Se manda a Meta? |
|---|---|
Cualquiera con parameters (header, body, button) | Sí |
Carrusel cuyas cards traen card_index | Sí |
El BODY con el texto, o el HEADER con format, sin parameters | No. Queda para mostrar el mensaje en la bandeja |
Cards de la definición, sin card_index | No. Si pasaran, Meta responde un error de clave format inesperada |
index del botón es la posición en la plantilla, desde cero, en string ("0", "1"). Un QUICK_REPLY no lleva parámetros de envío: no lo agregues.
La imagen
El link tiene que ser https. Waspy lo baja, lo normaliza y lo reemplaza por un id de media de Meta. Si la bajada o la subida fallan, el componente sigue con el link original y Meta intenta bajarlo. Un id que ya venga en el JSON no se vuelve a subir.
Ese paso existe porque un PNG de 16 bits, o un link que Meta no podía bajar, devolvía 131053 (media upload error) y el aviso no llegaba. JPEG o PNG comunes en una URL pública son el caso de todos los días. No hay upload de bytes en la v2: si el archivo solo vive en tu disco, primero tiene que estar en una URL pública.
El botón
La plantilla aprobada ya tiene el dominio, por ejemplo https://mitienda.com.ar/pago/{{1}}. El parámetro es el tramo variable, 1847/abc, no la URL completa. Si mandás la URL entera, Meta la concatena al prefijo y el cliente abre una dirección rota.
En los avisos de carrito de Tiendanube el sufijo es {id}/{token} y la barra no se codifica como %2F: esa forma responde 404 en el checkout. Es el mismo criterio si tu botón apunta a ese path. Un botón de URL sin {{1}} no se incluye en el POST.
Si algo no coincide
El POST no revisa que la plantilla esté approved ni que la cantidad de parámetros cierre. Encola y responde 201. El rechazo llega después:
| Qué ves | Cuándo |
|---|---|
| 132000 | Sobran o faltan parámetros respecto de la plantilla |
| 131053 | Meta no pudo usar la imagen |
failed en GET /api/v2/messages/:id | El errorCode de ese intento |
TEMPLATE_NOT_FOUND es el 404 de GET /api/v2/templates/:id y de GET /api/v2/templates/by-name/:name. No es la respuesta de este POST. Listar con status=approved, en minúscula, está en la nota de envío.
Si la categoría vigente es marketing y el número ya aceptó la Marketing Messages API, el mismo JSON sale por /marketing_messages. Utilidad y autenticación salen por /messages. El integrador no cambia la URL. El calendario de ese cambio está en marketing y la Cloud API en 2027.
Precio y plan
Meta cobra el mensaje entregado. En Argentina, desde el 1 de octubre de 2026, una utilidad sale alrededor de ARS 37,68 (~US$0,026) y un marketing alrededor de ARS 89,56 (~US$0,0618). Un botón de pago dentro de un aviso de pedido no lo vuelve gratis. Si el texto tiene un descuento, puede ser marketing. Waspy no suma un porcentaje. La fuente es la rate card.
La API está en Scale (US$150 por mes) y Enterprise. Diez días sin tarjeta, en el registro. Los planes están en Planes y el mapa de la API, en la página de la API.
