API de WhatsApp

Envía WhatsApp desde tu sistema con el número de tu empresa conectado en el panel (WhatsApp → Números). La autenticación es la del resto de la APIv3: una clave de API creada en el panel (Configuración → Claves de API) con permiso de WhatsApp.

  • URL base: https://www.mundosms.es/APIv3/
  • Método: POST, cuerpo JSON, cabecera Authorization: Bearer <token> y, si tu clave exige firma, X-Signature.
  • Respuesta: JSON con status (ok | error), status_code ("0" = correcto) y message.

Permisos de la clave

permiso qué permite
whatsapp todo lo de WhatsApp
whatsapp_send enviar mensajes
whatsapp_campaign crear, consultar y controlar envíos masivos
whatsapp_status, whatsapp_templates, whatsapp_numbers las consultas de cada método
all todo, como en el resto de la API

Una clave con read o write a secas (las de SMS o voz) no entra a WhatsApp. Si marcas a la vez «Todos lectura» y «Todos escritura», el panel la guarda como all, y all sí entra.

Firma y ts (si tu clave exige firma)

firma = base64url( HMAC-SHA256( secreto, token + "." + cuerpo_json ) )      # sin relleno "="
  • El cuerpo firmado tiene que incluir ts: la hora actual en segundos (epoch), a menos de 5 minutos de la de nuestro servidor.
  • Cada petición firmada vale una sola vez: la misma firma repetida devuelve Duplicated request. Para reintentar tras un error de red, vuelve a firmar con un ts nuevo.
  • Firma los bytes exactos que mandas: si reformateas el JSON después de firmar, la firma no vale.

Para todas las claves: si la clave tiene lista de IPs, solo se aceptan peticiones desde ellas.

Códigos de status_code

código qué pasa qué hacer
0 correcto —
2 error interno o sin conexión con WhatsApp si retry es true, reintenta en unos segundos
3 autenticación, permiso o parámetros corrige la petición (detail dice qué)
4 no encontrado en tu cuenta (número, plantilla, mensaje o envío masivo) —
5 sin saldo (Insufficient Credit, como en los SMS) recarga
6 la plantilla no cumple las reglas de WhatsApp —
7 demasiadas peticiones seguidas reintenta pasados retry_after segundos
8 fuera de las 24 h: el cliente no te ha escrito en las últimas 24 h manda una plantilla
9 el número no tiene la cuota mensual activa (reason: pending o expired) actívala en el panel
10 mensajes del mes agotados y el número no admite exceso (used, included) activa el exceso en el panel o espera al día 1
11 WhatsApp no contestó y el mensaje puede haber salido consulta whatsapp_status con el message_id antes de reintentar: si reintentas a ciegas, el cliente puede recibirlo dos veces. Si no trae message_id (un documento que tardó más de 50 s en subir), míralo en el Historial del panel
12 WhatsApp lo rechazó (whatsapp_error_code, p. ej. 131026: ese teléfono no tiene WhatsApp) no reintentes, salvo que retry sea true

Si el mensaje llegó a crearse, el error trae su message_id. detail lleva el texto original del error para el soporte, sin traducir.

whatsapp_numbers — tus números

curl -s https://www.mundosms.es/APIv3/whatsapp_numbers.php -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"ts": 1791100000}'
{"status":"ok","status_code":"0","message":"OK","numbers":[{"account_id":12,"number":"+34 881 92 28 02","name":"Clínica Sonríe",
 "quality":"GREEN","messaging_limit":"TIER_1K","coexistence":true,
 "monthly_fee":{"state":"active","active":true,"until":"2026-12-10","auto_renew":true},
 "monthly_usage":{"used":2350,"included":10000,"overage_allowed":true}}]}
  • account_id sirve para elegir número en las demás llamadas; si no lo indicas, se usa el primero.
  • monthly_fee.state: exempt, trial (primer mes gratis), active, pending o expired. Sin la cuota activa, los envíos dan 9.
  • monthly_usage: los mensajes de conversación del mes (los que recibes y los que contestas); included es null si el número no tiene límite. Agotados (included) y con overage_allowed a false, los textos dan 10. Las plantillas se cobran aparte y siguen saliendo.

whatsapp_templates — plantillas y su estado

-d '{"account_id": 12, "ts": 1791100000}'

Devuelve templates. Cada una trae:

  • name, language y body;
  • category: utility, marketing o authentication;
  • status: approved, pending o rejected;
  • vars: cuántos huecos {{1}}, {{2}}… hay que rellenar.

Las plantillas se crean en el panel.

whatsapp_send — enviar un mensaje

Para escribir primero a un cliente, o pasadas 24 h desde su último mensaje, hace falta una plantilla aprobada:

curl -s https://www.mundosms.es/APIv3/whatsapp_send.php -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"to":"34600000001","type":"template","template":{"name":"confirmacion_cita","language":"es","vars":["Ana","martes 16","17:30"]},
       "client_ref":"cita-881","ts":1791100000}'

Si el cliente te escribió en las últimas 24 h, también texto libre (hasta 4.096 caracteres):

-d '{"to":"34600000001","type":"text","text":"Hola Ana, ¿en qué te ayudamos?","ts":1791100000}'
{"status":"ok","status_code":"0","message":"OK","message_id":123,"wamid":"wamid.HBgL…","credits":0.2}
  • message_id: para consultar el estado.
  • wamid: el identificador de WhatsApp.
  • credits: lo que se ha descontado de tu saldo. Una plantilla cuesta créditos; una respuesta dentro de las 24 h entra en los mensajes del mes, y pasado el límite se cobra como exceso si el número lo admite.
  • to: con prefijo de país. Valen + y espacios, y un móvil español de 9 cifras se completa con 34.
  • client_ref: tu referencia libre (hasta 100 caracteres), que vuelve en whatsapp_status.
  • La categoría de la plantilla es la que WhatsApp le aprobó: no se elige al enviar.

Documentos y fotos

Igual que el texto libre, solo dentro de las 24 h desde el último mensaje del cliente (fuera: código 8). El fichero va en base64 dentro del JSON:

-d '{"to":"34600000001","type":"document","document":{"filename":"factura-881.pdf","base64":"JVBERi0xLjQK…",
     "caption":"Tu factura de noviembre"},"client_ref":"fra-881","ts":1791100000}'
-d '{"to":"34600000001","type":"image","image":{"base64":"/9j/4AAQSkZJRgABAQ…","caption":"Así queda"},"ts":1791100000}'

La respuesta es la misma que la del texto (message_id, wamid, credits), y whatsapp_status da type document o image.

  • filename: obligatorio en los documentos, con su extensión. Es el nombre que verá el cliente. Admitidos: pdf, doc, docx, xls, xlsx, ppt, pptx y txt. En las fotos, jpg o png, y el nombre es opcional: sin él, el tipo se reconoce por el contenido.
  • base64: el fichero entero. Se admiten saltos de línea y el prefijo data:application/pdf;base64,.
  • Tamaño máximo: 16 MB los documentos y 5 MB las fotos, que es el tope de WhatsApp.
  • caption: el texto que acompaña al fichero, opcional, hasta 1.024 caracteres.
  • Se comprueba que el contenido sea lo que dice el nombre: un fichero que no es un PDF de verdad pero se llama .pdf vuelve con código 3, y detail dice el motivo. Lo mismo un tipo no admitido o un fichero demasiado grande.
  • Un documento cuenta como un mensaje más del mes, igual que un texto.
  • Si WhatsApp no acepta el fichero al subirlo, vuelve el código 12 con whatsapp_error_code, y no se ha enviado nada.
  • Si la subida tarda más de 50 s, vuelve el código 11 sin message_id: el envío puede completarse después. No lo repitas sin mirar antes el Historial del panel.
  • Una vez enviado, el documento aparece en el Historial del panel como si lo hubieras mandado desde allí.

whatsapp_status — estado de un mensaje

-d '{"message_id": 123, "ts": 1791100000}'
{"status":"ok","status_code":"0","message":"OK","message_id":123,"to":"34600000001","type":"template","template":"confirmacion_cita",
 "state":"delivered","error_code":null,"error":null,"wamid":"wamid.HBgL…","credits":0.2,"client_ref":"cita-881",
 "created":"2026-11-11T09:30:00Z","updated":"2026-11-11T09:30:04Z"}

Los valores de state:

  • pending: creado. Si se queda así tras un 11, WhatsApp no ha dicho nada todavía.
  • accepted → sent → delivered → read.
  • failed: WhatsApp no pudo entregarlo, con error_code y error.
  • rejected: no salió.
  • excluded: el destinatario se dio de baja.

Las fechas van en ISO 8601, en UTC.

whatsapp_campaign — envío masivo

Crear (hasta 10.000 destinatarios por llamada; para más, varias llamadas):

curl -s https://www.mundosms.es/APIv3/whatsapp_campaign.php -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"action":"create","name":"Recordatorio citas lunes","template":{"name":"confirmacion_cita","language":"es"},
       "recipients":[{"to":"34600000001","vars":["Ana","lunes 6","10:00"]},{"to":"34600000002","vars":["Luis","lunes 6","11:30"]}],
       "scheduled_at":"2026-10-05T18:00:00+02:00","ts":1791100000}'
  • Respuesta: campaign_id, recipients, rejected_rows (teléfonos no válidos o repetidos) y state.
  • Consultar: {"action":"status","campaign_id":45}. Devuelve:
    • state, stop_reason y scheduled_at;
    • los contadores total, delivered, read, failed, excluded_optout y pending.
  • Controlar: {"action":"pause"|"resume"|"cancel","campaign_id":45}.
  • Estados: draft, scheduled, sending, paused, finished, cancelled y error.
  • Cobro: cada mensaje se cobra al salir, como un envío de plantilla. Sin saldo, el envío se pausa, y stop_reason dice por qué.

Los contactos que respondieron BAJA o STOP se excluyen automáticamente de los envíos.

Lo que todavía no hace la API

  • Enviar audios, vídeos o stickers: desde el panel sí, desde la API todavía no.
  • Rellenar la cabecera o los botones variables de una plantilla: solo los huecos del cuerpo (vars).
  • Crear plantillas: se crean en el panel.
  • Recibir los mensajes de tus clientes: eso no va por la API, sino por el webhook. Se configura en el panel y está documentado en https://www.mundosms.es/whatsapp-webhook.

Buenas prácticas

  • Permiso: escribe solo a quien ha aceptado recibir WhatsApp de tu empresa. Si te bloquean o te reportan, WhatsApp baja la calidad de tu número y reduce cuántos mensajes puedes enviar al día.
  • Tipo de plantilla: usa plantillas de aviso (utility) para recordatorios, confirmaciones y avisos de servicio. Las promocionales (marketing) cuestan más y tienen límites de frecuencia por usuario.
  • Reintentos: reintenta solo con retry: true, y con el código 11 consulta antes el estado.

¿Dudas con la integración? Escríbenos y te ayudamos. Para recibir en tu sistema los mensajes y los estados, tienes el webhook de WhatsApp, y aquí todo sobre la WhatsApp Business API de MundoSMS.


MundoSMS es proveedor tecnológico de la WhatsApp Business Platform de Meta. WhatsApp es una marca de Meta Platforms, Inc.; MundoSMS no está afiliado a Meta.