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 mediante Bearer Token (JWT).

URL Base: https://api.easywha.com

1. Autenticación

Para usar la API, primero debes obtener un token JWT. Este token tiene una duración de 1 hora y debe ser incluido en el encabezado Authorization de todas tus solicitudes como Bearer <token>.

POST

/api/auth/apikey-login

Obtiene un token JWT de corta duración usando tus credenciales de API.

Cuerpo de la Solicitud (JSON)

Parámetro	Tipo	Descripción
clientId	string	El "Client ID" que generaste en tu panel para el número de WhatsApp.
clientSecret	string	El "Client Secret" asociado a ese Client ID.

Ejemplo de Solicitud

curl -X POST https://api.easywha.com/api/auth/apikey-login \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "tu_client_id",
    "clientSecret": "tu_client_secret"
  }'

Respuesta Exitosa (200 OK)

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600
}

2. Envío de Mensajes

POST

/api/whatsapp/send

Envía un mensaje de texto a un contacto o grupo.

Cuerpo de la Solicitud (JSON)

Parámetro	Tipo	Descripción
accountId	integer	ID interno del número de WhatsApp desde el que se enviará. Debe coincidir con el del token.
number	string	Número del destinatario en formato internacional (ej: `521999...`) o JID (`...@c.us` o `...@g.us`).
message	string	Contenido del mensaje de texto.
replyTo	string (opcional)	`message_id` del mensaje al que se quiere responder.
mentions	array (opcional)	Array de JIDs a mencionar en un grupo (ej: `["521...c.us"]`).

Respuesta Exitosa (200 OK)

{
  "success": true,
  "msgId": "true_521...@c.us_3EB0..._3EB0...",
  "remainingQuota": 99
}

POST

/api/whatsapp/sendMedia

Envía un archivo multimedia (imagen, video, audio, documento).

Cuerpo de la Solicitud (multipart/form-data)

Parámetro	Tipo	Descripción
accountId	integer	ID del número de WhatsApp.
number	string	Número del destinatario.
file	file	El archivo a enviar.
caption	string (opcional)	Texto o pie de foto para el archivo.
replyTo	string (opcional)	`message_id` al que responder.

Respuesta Exitosa (200 OK)

La respuesta es idéntica a la del envío de texto.

3. Consulta de Chats y Mensajes

GET

/api/chats/{accountId}

Lista todos los chats asociados a un número de WhatsApp.

Respuesta Exitosa (200 OK)

{
  "success": true,
  "chats": [
    {
      "id": 123,
      "contact_number": "521999...",
      "contact_name": "Juan Pérez",
      "profile_pic_url": "https://...",
      "last_message": "¿Precio?",
      "updated_at": "2025-10-11T02:58:00Z",
      "chat_status": "Abierto",
      "user_id_assigned": null
    }
  ]
}

GET

/api/messages/chats/{chatId}/messages

Obtiene los mensajes de un chat específico, con paginación.

Parámetros de Consulta (Query)

Parámetro	Tipo	Descripción
limit	integer (opcional)	Número de mensajes a obtener. Por defecto: 50.
before	timestamp (opcional)	Timestamp para cargar mensajes más antiguos.
since	timestamp (opcional)	Timestamp para cargar mensajes nuevos.

Respuesta Exitosa (200 OK)

{
  "success": true,
  "messages": [
    {
      "id": 7771,
      "message_id": "true_521...@c.us_3EB0...",
      "sender": "521999...@c.us",
      "receiver": "529992...@c.us",
      "message": "Hola",
      "direction": "inbound",
      "timestamp": "2025-10-11T02:50:00Z"
    }
  ]
}