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 -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:
{ "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.