Mensajes
Enviar un mensaje de WhatsApp a un número y consultar en qué quedó. Una plantilla aprobada sale a cualquier número; un texto libre, solo si la persona te escribió en las últimas 24 h, y queda en su conversación de la bandeja para que el equipo lo vea. Hasta 1.000 envíos por clave y día (UTC) y 20 al mismo número. Ver la guía Enviar mensajes.
Enviar un mensaje
POST/messages
type: template envía una plantilla aprobada (templateId, y variables si las tiene) a cualquier número: si el número no es de ningún contacto, lo crea con contactName, y el coste se cobra del saldo. type: text envía text por la conversación de la bandeja, solo si la persona escribió en las últimas 24 h. Sale por phoneNumberId o, si falta, por la primera línea conectada. Nunca a quien retiró el consentimiento. Manda siempre Idempotency-Key: ante un 502 SEND_UNCERTAIN el mensaje pudo salir, y reintentar con la misma clave no lo duplica. Necesita messages:send.
Permisos: messages:send
Parámetros
| Nombre | Dónde | Tipo | Valores |
|---|---|---|---|
Idempotency-Key | cabecera | string | 1–255 caracteres |
Cuerpo de la petición SendMessage
| Nombre | Tipo | Valores |
|---|---|---|
to obligatorio | string | 0–32 caracteres · ^[+\d\s().-]+$ |
type obligatorio | string | template · text |
templateId | uuid | |
variables | object | |
text | string | 0–4096 caracteres |
phoneNumberId | uuid | |
contactName | string | 0–120 caracteres |
Errores frecuentes
- 400
INVALID_PHONEEl número no es válido: usa el formato internacional. - 400
TEMPLATE_NOT_APPROVEDLa plantilla todavía no está aprobada por Meta. - 400
CONTACT_OPTED_OUTLa persona retiró su consentimiento: no se le envía nada. - 400
NO_PHONE_NUMBERNo hay una línea de WhatsApp conectada (ophoneNumberIdno es tuya). - 404
TEMPLATE_NOT_FOUNDLa plantilla no existe o no es de tu organización. - 409
OUTSIDE_SERVICE_WINDOWPasaron más de 24 h desde el último mensaje de la persona, o nunca escribió: envía una plantilla. - 409
NO_INBOXLa línea no tiene bandeja para texto libre: envía una plantilla. - 429
DAILY_LIMIT_REACHEDLa clave ya hizo 1.000 envíos hoy (UTC). - 429
RECIPIENT_DAILY_LIMIT_REACHEDEse número ya recibió 20 mensajes por la API hoy (UTC). - 502
SEND_UNCERTAINNo sabemos si salió. Reintenta solo con la mismaIdempotency-Key. - 502
INBOX_UNAVAILABLELa bandeja no respondió; vuelve a intentarlo en un momento.
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"
}'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();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
$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);{
"id": "tpl_6f1c2b9e-3a4d-4e5f-8a7b-9c0d1e2f3a4b",
"type": "template",
"to": "+34600111222",
"status": "PENDING",
"error": null
}Estado de un mensaje
GET/messages/{id}
Con el id que devolvió el envío: PENDING, SENT, DELIVERED, READ o FAILED (con el motivo en error). Un texto antiguo que ya no aparece en la conversación vuelve como UNKNOWN. En el estado de un texto, to es null. Responde 404 si el mensaje no es de tu organización. Necesita messages:send.
Permisos: messages:send
Parámetros
| Nombre | Dónde | Tipo | Valores |
|---|---|---|---|
id obligatorio | ruta | string |
curl "https://micuenta.whatsmarketing.es/api/v1/messages/{id}" \
-H "Authorization: Bearer $WM_API_KEY"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();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
$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);{
"id": "tpl_6f1c2b9e-3a4d-4e5f-8a7b-9c0d1e2f3a4b",
"type": "template",
"to": "+34600111222",
"status": "READ",
"error": null
}