Documentación de la API
Guía para integrar tus aplicaciones con la API de EasyWha.
Introducción
La API de EasyWha te permite enviar y recibir mensajes de WhatsApp, consultar chats y más, de forma programática. Está diseñada bajo principios REST, utiliza JSON para la comunicación y requiere autenticación segura.
URL Base: https://api.easywha.com
1. Autenticación
La API utiliza tokens JWT (JSON Web Tokens) para garantizar la seguridad. Antes de realizar cualquier petición, debes intercambiar tus credenciales (clientId y clientSecret) por un token de acceso temporal.
1.1 Obtener Token de Acceso
Intercambia tus credenciales por un token válido por 1 hora.
Cuerpo de la Solicitud (JSON)
{
"clientId": "TU_CLIENT_ID",
"clientSecret": "TU_CLIENT_SECRET"
}Ejemplo de Solicitud (cURL)
curl -X POST https://api.easywha.com/api/auth/apikey-login \
-H "Content-Type: application/json" \
-d '{
"clientId": "mi_client_id",
"clientSecret": "mi_client_secret"
}'Respuesta Exitosa (200 OK)
{
"success": true,
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 3600
}1.2 Usar el Token en las Peticiones
Una vez tengas el token, debes incluirlo en el encabezado Authorization de todas tus solicitudes siguientes. Note que el token expira después del tiempo indicado.
Authorization: Bearer <TU_ACCESS_TOKEN>2. Envío de Mensajes
2.1 Enviar Texto
Envía un mensaje de texto simple a cualquier número de WhatsApp.
Cuerpo de la Solicitud (JSON)
| Parámetro | Tipo | Descripción |
|---|---|---|
| accountId | integer | ID de la cuenta emisora. |
| number | string | Número del destinatario en formato internacional (ej: `521999...`) o JID. |
| message | string | Contenido del mensaje de texto. |
Ejemplo de Solicitud (cURL)
curl -X POST https://api.easywha.com/api/whatsapp/send \
-H "Content-Type: application/json" \
-H "Authorization: Bearer tu_access_token" \
-d '{
"accountId": 123,
"number": "5219991234567",
"message": "Hola, esto es una prueba desde la API."
}'Respuesta Exitosa (200 OK)
{
"success": true,
"msgId": "true_521...@c.us_3EB0...",
"remainingQuota": 99
}2.2 Enviar Archivos Multimedia
Envía imágenes, videos, audios o documentos.
Cuerpo de la Solicitud (multipart/form-data)
| Parámetro | Tipo | Descripción |
|---|---|---|
| file | file | El archivo binario a enviar. |
| accountId | integer | ID de la cuenta emisora. |
| number | string | Número de destino (ej. `5219991234567`). |
| caption | string (opcional) | Texto que acompaña al archivo. |
Ejemplo de Solicitud (cURL)
curl -X POST https://api.easywha.com/api/whatsapp/sendMedia \
-H "Authorization: Bearer tu_access_token" \
-F "file=@/ruta/imagen.jpg" \
-F "accountId=123" \
-F "number=5219991234567" \
-F "caption=Mira esta imagen"3. Consulta de Chats y Mensajes
3.1 Listar Chats
:accountId - El ID numérico de tu cuenta o tu número de teléfono (ej. 5219990000000).
Ejemplo de Solicitud (cURL)
curl -X GET https://api.easywha.com/api/chats/5219990000000 \
-H "Authorization: Bearer tu_access_token"Respuesta Exitosa (200 OK)
{
"success": true,
"chats": [
{
"id": 123,
"contact_number": "5219991234567",
"contact_name": "Juan Pérez",
"profile_pic_url": "https://...",
"last_message": "¿Cuál es el precio?",
"updated_at": "2025-10-11T02:58:00Z",
"unread_count": 2
}
]
}3.2 Listar Historial de Mensajes
Parámetros (Query)
| Parámetro | Tipo | Descripción |
|---|---|---|
| limit | integer (opcional) | Cantidad de mensajes (default: 50). |
| before | string (opcional) | ID de mensaje o timestamp para paginación. |
Ejemplo de Solicitud (cURL)
curl -X GET "https://api.easywha.com/api/chats/123/messages?limit=20" \
-H "Authorization: Bearer tu_access_token"Respuesta Exitosa (200 OK)
{
"success": true,
"messages": [
{
"id": 7771,
"message_id": "true_521...@c.us_3EB0...",
"direction": "inbound",
"message": "Hola, quiero información",
"timestamp": "2025-10-11T02:50:00Z",
"status": "read"
},
{
"id": 7772,
"direction": "outbound",
"message": "Claro, en qué te ayudo?",
"timestamp": "2025-10-11T02:51:00Z",
"status": "sent"
}
]
}3.3 Marcar Mensajes como Leídos
curl -X POST https://api.easywha.com/api/chats/123/mark-read \
-H "Authorization: Bearer tu_access_token"4. Webhooks (Recepción en Tiempo Real)
Configura una URL en tu panel para recibir notificaciones POST por cada mensaje entrante.
4.1 Seguridad (Encriptación)
Por seguridad, el contenido se envía encriptado con AES-256-CBC usando tu Client Secret (¡no tu token!) como llave.
{
"iv": "a1b2c3d4...", // Vector de inicialización (Hex)
"data": "f9e8d7..." // Mensaje encriptado (Hex)
}4.2 Ejemplo de Desencriptación (Node.js)
const crypto = require('crypto');
const API_KEY = 'tu_client_secret';
app.post('/webhook', (req, res) => {
const { iv, data } = req.body;
try {
const key = Buffer.from(API_KEY, 'hex');
const ivBuffer = Buffer.from(iv, 'hex');
const decipher = crypto.createDecipheriv('aes-256-cbc', key, ivBuffer);
let decrypted = decipher.update(data, 'hex', 'utf8');
decrypted += decipher.final('utf8');
const message = JSON.parse(decrypted);
console.log("Mensaje:", message);
res.sendStatus(200);
} catch (e) {
res.sendStatus(400);
}
});4.3 Validación (Ping)
Al registrar tu URL, nuestro sistema enviará un POST de prueba (no encriptado) para validar la conectividad:
{ "type": "ping" }Tu servidor debe responder obligatoriamente con status 200 OK. De lo contrario, no se guardará el webhook.
5. Códigos de Error Comunes
401 Unauthorized: Token inválido o expirado.403 Forbidden: Acceso denegado (IP no permitida o cuenta ajena).404 Not Found: Recurso no encontrado.500 Internal Server Error: Error del servidor o de WhatsApp Web.