Ir al contenido
WhatsMarketingDeveloper Hub

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

NombreDóndeTipoValores
Idempotency-Keycabecerastring1–255 caracteres

Cuerpo de la petición SendMessage

NombreTipoValores
to obligatoriostring0–32 caracteres · ^[+\d\s().-]+$
type obligatoriostringtemplate · text
templateIduuid
variablesobject
textstring0–4096 caracteres
phoneNumberIduuid
contactNamestring0–120 caracteres

Errores frecuentes

  • 400 INVALID_PHONE El número no es válido: usa el formato internacional.
  • 400 TEMPLATE_NOT_APPROVED La plantilla todavía no está aprobada por Meta.
  • 400 CONTACT_OPTED_OUT La persona retiró su consentimiento: no se le envía nada.
  • 400 NO_PHONE_NUMBER No hay una línea de WhatsApp conectada (o phoneNumberId no es tuya).
  • 404 TEMPLATE_NOT_FOUND La plantilla no existe o no es de tu organización.
  • 409 OUTSIDE_SERVICE_WINDOW Pasaron más de 24 h desde el último mensaje de la persona, o nunca escribió: envía una plantilla.
  • 409 NO_INBOX La línea no tiene bandeja para texto libre: envía una plantilla.
  • 429 DAILY_LIMIT_REACHED La clave ya hizo 1.000 envíos hoy (UTC).
  • 429 RECIPIENT_DAILY_LIMIT_REACHED Ese número ya recibió 20 mensajes por la API hoy (UTC).
  • 502 SEND_UNCERTAIN No sabemos si salió. Reintenta solo con la misma Idempotency-Key.
  • 502 INBOX_UNAVAILABLE La bandeja no respondió; vuelve a intentarlo en un momento.
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);
Respuesta 200
{
  "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

NombreDóndeTipoValores
id obligatoriorutastring
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);
Respuesta 200
{
  "id": "tpl_6f1c2b9e-3a4d-4e5f-8a7b-9c0d1e2f3a4b",
  "type": "template",
  "to": "+34600111222",
  "status": "READ",
  "error": null
}