Skip to content
WhatsMarketingDeveloper Hub

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
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:

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