Documentación de la API
Todo lo necesario para enviar mensajes de WhatsApp desde tus sistemas.
Primeros pasos
- Crea tu cuenta y vincula tu WhatsApp desde Mis números.
- En Claves API, crea una clave. Guárdala: solo se muestra una vez.
- Abre este enlace en el navegador, con tu clave. Te llegará un mensaje a ti mismo:
/api/send?text=Hola&apikey=TU_CLAVE
Enviar un mensaje
Hay dos formas equivalentes. Usa la que te resulte más cómoda.
Enlace sencillo (GET o POST de formulario)
/api/send?phone=612345678&text=Tu%20pedido%20sale%20hoy&apikey=TU_CLAVE
Acepta los parámetros en la dirección o como formulario (application/x-www-form-urlencoded). También responde en /send.php.
API REST (JSON)
POST /api/v1/messages
Authorization: Bearer TU_CLAVE
Content-Type: application/json
{ "to": "612345678", "text": "Tu pedido sale hoy" }
Parámetros
| Parámetro | Obligatorio | Descripción |
|---|---|---|
apikey | Sí | Tu clave. En la API REST va en la cabecera Authorization: Bearer. |
phone o to | No | Destinatario. Sin él, el mensaje te llega a tu propio número: ideal para avisos internos. También se acepta recipient. |
group | No | ID de un grupo de WhatsApp en lugar de un número. Mira Grupos. |
from | No | Número emisor si tienes varios: su ID, su nombre o el número. Sin él se usa el principal. |
text | Sí, salvo con archivo | Texto del mensaje, hasta 4.000 caracteres. Admite emojis y el formato de WhatsApp: *negrita*, _cursiva_. |
file | No | Enlace público a una imagen, PDF, vídeo o audio. El texto se envía como pie. |
format | No | Con json, el enlace sencillo responde en JSON en lugar de texto. |
lang | No | Idioma de los mensajes de error: es, en, pt o fr. |
Grupos
Disponible en el plan Pro y superiores, y durante la prueba gratuita. Tu número debe ser miembro del grupo. En el panel, Mis números → Ver grupos muestra cada grupo con su ID. También puedes consultarlos por API:
GET /api/v1/groups
Authorization: Bearer TU_CLAVE
{"ok":true,"groups":[{"id":"120363012345678901","name":"Comerciales","size":6}]}
/api/send?group=120363012345678901&text=Reunión%20a%20las%2010&apikey=TU_CLAVE
En JSON también vale "to": "[email protected]". Los grupos están disponibles con números vinculados por QR.
Varios números
Si tu cuenta tiene varios números, elige el emisor con from. Acepta el ID que aparece en el panel, el nombre que le hayas dado (por ejemplo Taller) o el propio número de teléfono.
/api/send?from=Taller&phone=612345678&text=Tu%20equipo%20está%20listo&apikey=TU_CLAVE
Cada número tiene su propia cola: los envíos de un número no esperan a los de otro.
Imágenes y documentos
Añade file con un enlace que se pueda descargar sin iniciar sesión. Máximo 16 MB.
/api/send?phone=612345678&text=Albarán%20adjunto&file=https://drive.google.com/file/d/ID/view&apikey=TU_CLAVE
Los enlaces de Google Drive del tipo «Cualquier persona con el enlace» se convierten automáticamente en descarga directa.
Respuestas de la API
Los mensajes no se envían en el momento de la petición: entran en una cola y salen en orden, con pausas de unos segundos para proteger tu número. La respuesta confirma que el mensaje está en cola.
Enlace sencillo: 200 Mensaje en cola. id=123
API REST: 202 {"ok":true,"id":123,"status":"queued","to":"34612345678","from":5}
| Código | Qué significa | Qué hacer |
|---|---|---|
| 400 | Falta el texto, el número no es válido o el emisor no existe | Revisa los parámetros |
| 401 | Clave incorrecta o borrada | Crea una clave nueva en tu panel |
| 402 | La prueba gratuita ha terminado | Elige un plan en tu panel |
| 403 | Cuenta desactivada, o clave del bot usada para otro destino | Contacta con soporte |
| 429 | Demasiadas peticiones por minuto o límite diario alcanzado | Espera, o amplía tu plan |
Estado de un mensaje
GET /api/v1/messages/123
Authorization: Bearer TU_CLAVE
{"ok":true,"message":{"id":123,"status":"sent","attempts":1,"error":null, ...}}
Estados: queued (en cola), sending, sent (entregado a WhatsApp) y failed (no enviado, con el motivo en error). Si un número se desconecta, sus mensajes esperan y se reintentan solos.
Estado de tus números: GET /api/v1/status
Formato de los números
Funciona con números de cualquier país. Puedes escribirlos en formato internacional (+44 7911 123456, 0044…) o en formato local de tu país (07911 123456). Sin prefijo, se usa el país de tu cuenta, configurable en Ajustes.
El sistema conoce las reglas de numeración de cada país: quita el 0 o el prefijo nacional cuando corresponde y añade el código del país. Por ejemplo, 06 12 34 56 78 en Francia pasa a ser +33 6 12 34 56 78 y (11) 98765-4321 en Brasil pasa a ser +55 11 98765 4321.
Límites
- Mensajes al día: según tu plan. Lo ves en el inicio de tu panel.
- Peticiones: hasta 30 por minuto por clave.
- Entre mensajes del mismo número hay unos segundos de pausa para que WhatsApp no lo considere spam.
Envía solo mensajes que tus destinatarios esperan. Los envíos masivos a personas que no te conocen pueden hacer que WhatsApp restrinja tu número.
Recibir mensajes
En Ajustes puedes indicar una dirección https:// de tu sistema. Cada mensaje que reciba cualquiera de tus números se te reenviará así:
POST https://tu-sistema.com/webhook
Content-Type: application/json
X-Wagate-Signature: firma HMAC-SHA256 del cuerpo
{"event":"message.received","number_id":5,"from":"+34612345678","message":"SI","name":"Luis","group":null,"at":1762440000000}
Ejemplos
Google Apps Script
function enviarWhatsApp(telefono, texto) {
const r = UrlFetchApp.fetch('/api/send', {
method: 'post',
payload: { apikey: 'TU_CLAVE', phone: telefono, text: texto },
muteHttpExceptions: true,
});
return r.getResponseCode() === 200;
}
AppSheet
Automation, Bot, tarea «Call a webhook»: URL /api/v1/messages, verbo POST, tipo JSON, cabecera Authorization: Bearer TU_CLAVE y cuerpo:
{ "to": "<<[TELEFONO]>>", "text": "Hola <<[CLIENTE]>>, tu pedido está listo." }
PHP
file_get_contents('/api/send?' . http_build_query([
'apikey' => 'TU_CLAVE', 'phone' => '612345678', 'text' => 'Hola desde PHP',
]));
Python
import requests
requests.post('/api/v1/messages',
headers={'Authorization': 'Bearer TU_CLAVE'},
json={'to': '612345678', 'text': 'Hola desde Python'})