Volver al blog
Desarrolladores

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.

· 12 min
Cómo mandar una plantilla de WhatsApp con imagen y botón de URL por la API

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_indexSí
El BODY con el texto, o el HEADER con format, sin parametersNo. Queda para mostrar el mensaje en la bandeja
Cards de la definición, sin card_indexNo. 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é vesCuándo
132000Sobran o faltan parámetros respecto de la plantilla
131053Meta no pudo usar la imagen
failed en GET /api/v2/messages/:idEl 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.

Tu equipo atendiendo por WhatsApp en minutos

CRM facil pero potente. En 10 minutos tenes a tu equipo trabajando — no necesitas hablar con nadie.