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, cabeceraAuthorization: Bearer <token>y, si tu clave exige firma,X-Signature. - Respuesta: JSON con
status(ok|error),status_code("0"= correcto) ymessage.
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 untsnuevo. - 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_idsirve 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,pendingoexpired. 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);includedesnullsi el número no tiene límite. Agotados (included) y conoverage_allowedafalse, 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,languageybody;category:utility,marketingoauthentication;status:approved,pendingorejected;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 enwhatsapp_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,pptxytxt. En las fotos,jpgopng, 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 prefijodata: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
.pdfvuelve con código3, ydetaildice 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
12conwhatsapp_error_code, y no se ha enviado nada. - Si la subida tarda más de 50 s, vuelve el código
11sinmessage_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, conerror_codeyerror.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) ystate. - Consultar:
{"action":"status","campaign_id":45}. Devuelve:state,stop_reasonyscheduled_at;- los contadores
total,delivered,read,failed,excluded_optoutypending.
- Controlar:
{"action":"pause"|"resume"|"cancel","campaign_id":45}. - Estados:
draft,scheduled,sending,paused,finished,cancelledyerror. - Cobro: cada mensaje se cobra al salir, como un envío de plantilla. Sin saldo, el envío se pausa, y
stop_reasondice 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.