Sending messages
POST /messages sends a WhatsApp message to a number. It is what Make, Zapier, n8n or your CRM connectors use to notify a customer. The key needs the messages:send permission.
Template or free text
Template (type: template) |
Free text (type: text) |
|
|---|---|---|
| To whom | Any number | Only if the person wrote to you in the last 24 hours |
| What you send | templateId of an approved template and its variables |
text, up to 4,096 characters |
| Contact | If the number does not belong to a contact, one is created (with contactName) |
The conversation must exist |
| Where it shows | On the contact's record | In their inbox conversation, like any other team message |
| Cost | Charged to your balance, like a send from the panel | Same as a reply from the inbox |
Outside the 24 hours, free text returns 409 OUTSIDE_SERVICE_WINDOW: send a template. Nothing is sent to someone who withdrew consent (400 CONTACT_OPTED_OUT).
Sending a template
curl -X POST https://micuenta.whatsmarketing.es/api/v1/messages \
-H "Authorization: Bearer $WM_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-48213-notice" \
-d '{
"to": "+34600111222",
"type": "template",
"templateId": "6f1c2b9e-3a4d-4e5f-8a7b-9c0d1e2f3a4b",
"variables": { "1": "Ana" },
"contactName": "Ana García"
}'templateId values come from GET /whatsapp/templates (templates:read permission). Variables go by number: {"1": "Ana"} fills {{1}}. If you have several lines, phoneNumberId picks which one it goes out from; if missing, the first connected one.
The response carries the message id and its status:
{ "id": "tpl_6f1c2b9e-…", "type": "template", "to": "+34600111222", "status": "PENDING", "error": null }Checking the status
GET /messages/{id} returns PENDING, SENT, DELIVERED, READ or FAILED (with the reason in error). No need to rush: the status changes within seconds or minutes, so asking more than once a minute is not needed.
Retrying without duplicates
Always send Idempotency-Key with a value that identifies the send in your system (the order, the appointment, the notice). If you repeat the request with the same key within 24 hours, you get the same response and the message does not go out twice.
This matters with 502 SEND_UNCERTAIN: it means we do not know whether the message went out. Retry only with the same Idempotency-Key; without it, you might send it twice.
Limits
| Limit | Value | When exceeded |
|---|---|---|
| Sends per key per day (UTC) | 1,000 | 429 DAILY_LIMIT_REACHED |
| Sends to the same number per day (UTC) | 20 | 429 RECIPIENT_DAILY_LIMIT_REACHED |
POST /messages |
60 per minute per key | 429 API_KEY_RATE_LIMITED |
GET /messages/{id} |
120 per minute per key | 429 API_KEY_RATE_LIMITED |
To reach thousands of people at once, use a campaign (POST /campaigns): it splits the send into batches and shows the cost first. If you need more one-off sends per day, write to us.
Errors
Every code, with its explanation, is in the Messages reference.