Ir al contenido
WhatsMarketingDeveloper Hub

Enviar mensajes

POST /messages envía un mensaje de WhatsApp a un número. Es lo que usan los conectores de Make, Zapier, n8n o tu CRM para avisar a un cliente. La clave necesita el permiso messages:send.

Plantilla o texto libre

Plantilla (type: template) Texto libre (type: text)
A quién A cualquier número Solo si la persona te escribió en las últimas 24 h
Qué mandas templateId de una plantilla aprobada y sus variables text, hasta 4.096 caracteres
Contacto Si el número no es de ningún contacto, lo crea (con contactName) Tiene que existir la conversación
Dónde se ve En la ficha del contacto En su conversación de la bandeja, como un mensaje más del equipo
Coste Se cobra del saldo, como un envío desde el panel Igual que una respuesta desde la bandeja

Fuera de las 24 h el texto libre responde 409 OUTSIDE_SERVICE_WINDOW: envía una plantilla. A quien retiró el consentimiento no se le envía nada (400 CONTACT_OPTED_OUT).

Enviar una plantilla

curl
curl -X POST https://micuenta.whatsmarketing.es/api/v1/messages \
  -H "Authorization: Bearer $WM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-48213-aviso" \
  -d '{
      "to": "+34600111222",
      "type": "template",
      "templateId": "6f1c2b9e-3a4d-4e5f-8a7b-9c0d1e2f3a4b",
      "variables": { "1": "Ana" },
      "contactName": "Ana García"
    }'

Los templateId salen de GET /whatsapp/templates (permiso templates:read). Las variables van por número: {"1": "Ana"} rellena {{1}}. Si tienes varias líneas, phoneNumberId elige desde cuál sale; si falta, la primera conectada.

La respuesta trae el id del mensaje y su estado:

JSON
{ "id": "tpl_6f1c2b9e-…", "type": "template", "to": "+34600111222", "status": "PENDING", "error": null }

Consultar el estado

GET /messages/{id} devuelve PENDING, SENT, DELIVERED, READ o FAILED (con el motivo en error). Consulta con calma: el estado cambia en segundos o minutos, no hace falta preguntar más de una vez por minuto.

Reintentar sin duplicar

Manda siempre Idempotency-Key con un valor que identifique el envío en tu sistema (el pedido, la cita, el aviso). Si repites la petición con la misma clave en 24 h, recibes la misma respuesta y el mensaje no sale dos veces.

Es importante con 502 SEND_UNCERTAIN: significa que no sabemos si el mensaje salió. Reintenta solo con la misma Idempotency-Key; sin ella, podrías mandarlo dos veces.

Cupos

Cupo Valor Al superarlo
Envíos por clave y día (UTC) 1.000 429 DAILY_LIMIT_REACHED
Envíos al mismo número y día (UTC) 20 429 RECIPIENT_DAILY_LIMIT_REACHED
POST /messages 60 por minuto y clave 429 API_KEY_RATE_LIMITED
GET /messages/{id} 120 por minuto y clave 429 API_KEY_RATE_LIMITED

Para enviar a miles de personas a la vez usa una campaña (POST /campaigns): reparte el envío en tandas y muestra el coste antes. Si necesitas más envíos sueltos al día, escríbenos.

Errores

Todos los códigos, con su explicación, están en la referencia de Mensajes.