Skip to content
WhatsMarketingDeveloper Hub

Messages

Send a WhatsApp message to a number and check what happened to it. An approved template goes to any number; free text only if the person wrote to you in the last 24 hours, and it stays in their inbox conversation so your team can see it. Up to 1,000 sends per key per day (UTC) and 20 to the same number. See the Sending messages guide.

Send a message

POST/messages

type: template sends an approved template (templateId, plus variables if it has any) to any number: if the number does not belong to a contact, one is created with contactName, and the cost is charged to your balance. type: text sends text through the inbox conversation, only if the person wrote in the last 24 hours. It goes out from phoneNumberId or, if missing, the first connected line. Never to someone who withdrew consent. Always send Idempotency-Key: after a 502 SEND_UNCERTAIN the message may have gone out, and retrying with the same key does not duplicate it. Needs messages:send.

Scopes: messages:send

Parameters

NameWhereTypeValues
Idempotency-Keyheaderstring1–255 characters

Request body SendMessage

NameTypeValues
to requiredstring0–32 characters · ^[+\d\s().-]+$
type requiredstringtemplate · text
templateIduuid
variablesobject
textstring0–4096 characters
phoneNumberIduuid
contactNamestring0–120 characters

Common errors

  • 400 INVALID_PHONE The number is not valid: use the international format.
  • 400 TEMPLATE_NOT_APPROVED Meta has not approved the template yet.
  • 400 CONTACT_OPTED_OUT The person withdrew consent: nothing is sent to them.
  • 400 NO_PHONE_NUMBER No WhatsApp line is connected (or phoneNumberId is not yours).
  • 404 TEMPLATE_NOT_FOUND The template does not exist or is not your organization's.
  • 409 OUTSIDE_SERVICE_WINDOW More than 24 hours have passed since the person's last message, or they never wrote: send a template.
  • 409 NO_INBOX The line has no inbox for free text: send a template.
  • 429 DAILY_LIMIT_REACHED The key already made 1,000 sends today (UTC).
  • 429 RECIPIENT_DAILY_LIMIT_REACHED That number already received 20 messages via the API today (UTC).
  • 502 SEND_UNCERTAIN We do not know whether it went out. Retry only with the same Idempotency-Key.
  • 502 INBOX_UNAVAILABLE The inbox did not respond; try again in a moment.
curl
curl -X POST "https://micuenta.whatsmarketing.es/api/v1/messages" \
  -H "Authorization: Bearer $WM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "+34600111222",
  "type": "template",
  "templateId": "6f1c2b9e-3a4d-4e5f-8a7b-9c0d1e2f3a4b",
  "variables": {
    "1": "Ana"
  },
  "contactName": "Ana García"
}'
Node.js
const res = await fetch('https://micuenta.whatsmarketing.es/api/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WM_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "to": "+34600111222",
    "type": "template",
    "templateId": "6f1c2b9e-3a4d-4e5f-8a7b-9c0d1e2f3a4b",
    "variables": {
      "1": "Ana"
    },
    "contactName": "Ana García"
  }),
});
const data = await res.json();
Python
import os, requests

r = requests.post(
    "https://micuenta.whatsmarketing.es/api/v1/messages",
    headers={"Authorization": f"Bearer {os.environ['WM_API_KEY']}"},
    json={
        "to": "+34600111222",
        "type": "template",
        "templateId": "6f1c2b9e-3a4d-4e5f-8a7b-9c0d1e2f3a4b",
        "variables": {
            "1": "Ana"
        },
        "contactName": "Ana García"
    },
    timeout=30,
)
r.raise_for_status()
data = r.json()
PHP
<?php
$ch = curl_init('https://micuenta.whatsmarketing.es/api/v1/messages');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('WM_API_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'to' => '+34600111222',
    'type' => 'template',
    'templateId' => '6f1c2b9e-3a4d-4e5f-8a7b-9c0d1e2f3a4b',
    'variables' => [
      '1' => 'Ana'
    ],
    'contactName' => 'Ana García'
  ]),
]);
$data = json_decode(curl_exec($ch), true);
Response 200
{
  "id": "tpl_6f1c2b9e-3a4d-4e5f-8a7b-9c0d1e2f3a4b",
  "type": "template",
  "to": "+34600111222",
  "status": "PENDING",
  "error": null
}

Message status

GET/messages/{id}

With the id the send returned: PENDING, SENT, DELIVERED, READ or FAILED (with the reason in error). An old text that no longer appears in the conversation comes back as UNKNOWN. In a text's status, to is null. Returns 404 if the message is not your organization's. Needs messages:send.

Scopes: messages:send

Parameters

NameWhereTypeValues
id requiredpathstring
curl
curl "https://micuenta.whatsmarketing.es/api/v1/messages/{id}" \
  -H "Authorization: Bearer $WM_API_KEY"
Node.js
const res = await fetch('https://micuenta.whatsmarketing.es/api/v1/messages/{id}', {
  headers: {
    Authorization: `Bearer ${process.env.WM_API_KEY}`,
  },
});
const data = await res.json();
Python
import os, requests

r = requests.get(
    "https://micuenta.whatsmarketing.es/api/v1/messages/{id}",
    headers={"Authorization": f"Bearer {os.environ['WM_API_KEY']}"},
    timeout=30,
)
r.raise_for_status()
data = r.json()
PHP
<?php
$ch = curl_init('https://micuenta.whatsmarketing.es/api/v1/messages/{id}');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('WM_API_KEY'),
  ],
]);
$data = json_decode(curl_exec($ch), true);
Response 200
{
  "id": "tpl_6f1c2b9e-3a4d-4e5f-8a7b-9c0d1e2f3a4b",
  "type": "template",
  "to": "+34600111222",
  "status": "READ",
  "error": null
}