WhatAPI - Documentación oficial

Autenticación

Todas las peticiones a la API (excepto login y registro) requieren un token Bearer en el encabezado Authorization.

Header requerido:

Authorization: Bearer <tu_token>

Obtén tu token desde el Dashboard en la sección "Token de Acceso". Usa el token que empieza con wa_ (ej: wa_74ce1ce0b5dacf73...). Ese es el token de API para sistemas externos (PHP, JS, etc.).

Error 401: Si usas el token de sesión del navegador en lugar del token wa_, recibirás 401. Copia el token del Dashboard (el que se muestra en la caja gris) y úsalo en el header.

GET /api/token

Obtiene o genera tu token de acceso para usar la API. Debes estar autenticado (cookie de sesión o token previo).

GET /api/token

Ejemplos de código

curl --request GET \

  --url https://tu-dominio.com/api/token \

  --header 'Authorization: Bearer <tu_token>'

// Con cURL

$ch = curl_init('https://tu-dominio.com/api/token');

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

curl_setopt($ch, CURLOPT_HTTPHEADER, [

  'Authorization: Bearer ' . $tu_token

]);

$response = curl_exec($ch);

curl_close($ch);

$data = json_decode($response, true);

$token = $data['token'] ?? null;

const response = await fetch('https://tu-dominio.com/api/token', {

  headers: { 'Authorization': `Bearer ${token}` }

});

const data = await response.json();

const apiToken = data.token;

Respuesta 200 OK

{
  "token": "wa_74ce1ce0b5dacf73e471810aa848aff10483c45ccd6349fb"
}

GET /api/status

Retorna el estado del sistema: conexión API, WhatsApp y base de datos.

GET /api/status

Respuesta 200 OK

{
  "apiConnected": true,
  "whatsappConnected": true,
  "dbConnected": true,
  "uptime": 3600,
  "sessionStartedAt": 1710000000000
}

Instancias (Dispositivos)

Gestiona las instancias de WhatsApp conectadas a tu cuenta. Es obligatorio tener al menos una instancia conectada antes de enviar mensajes. Cada instancia requiere crear un dispositivo, conectarlo y escanear el QR con la app de WhatsApp.

GET /api/devices

Lista todos tus dispositivos.

GET /api/devices

Respuesta 200 OK

[
  {
    "id": "abc123",
    "name": "ventas",
    "phone": "51999999999",
    "status": "connected"
  }
]

POST /api/devices

Crea un nuevo dispositivo.

POST /api/devices

Parámetro	Tipo	Descripción
`name`	string	Nombre del dispositivo (ej: ventas, soporte)

POST /api/devices/:id/connect

Inicia la conexión del dispositivo. Genera el QR para escanear.

GET /api/devices/:id/qr

Obtiene el código QR (imagen base64) para vincular el dispositivo con WhatsApp.

DELETE /api/devices/:id

Elimina un dispositivo.

POST /api/send

Envía un mensaje de texto, imagen, video o documento a un número de WhatsApp.

Requisitos previos: Necesitas tu Token de acceso y al menos una instancia (dispositivo) creada y conectada. La instancia debe haber escaneado el QR desde WhatsApp antes de enviar mensajes. Obtén el deviceId con GET /api/devices.

POST /api/send

Parámetro	Tipo	Requerido	Descripción
`deviceId`	string	Sí	ID de la instancia (dispositivo) conectada. Crea una con `POST /api/devices` y conéctala escaneando el QR.
`to`	string	Sí	Número destino (ej: 51999999999). Se acepta con o sin código de país.
`message`	string	No*	Texto del mensaje. Obligatorio si no envías archivo.
`file`	archivo	No	Archivo adjunto (imagen, video, PDF, etc.) vía multipart/form-data

* Debes enviar al menos message o file.

Ejemplos de código

# Solo texto

curl --request POST \

  --url https://tu-dominio.com/api/send \

  --header 'Authorization: Bearer <tu_token>' \

  --header 'Content-Type: application/json' \

  --data '{"deviceId":"abc123","to":"51999999999","message":"Hola desde la API!"}'

# Con imagen

curl --request POST \

  --url https://tu-dominio.com/api/send \

  --header 'Authorization: Bearer <tu_token>' \

  --form 'deviceId=abc123' \

  --form 'to=51999999999' \

  --form 'message=Adjunto una foto' \

  --form 'file=@/ruta/imagen.jpg'

// Enviar mensaje de texto

$token = 'wa_tu_token_aqui';

$data = [

  'deviceId' => 'abc123',

  'to' => '51999999999',

  'message' => 'Hola desde PHP!'

];

$ch = curl_init('https://tu-dominio.com/api/send');

curl_setopt($ch, CURLOPT_POST, true);

curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

curl_setopt($ch, CURLOPT_HTTPHEADER, [

  'Authorization: Bearer ' . $token,

  'Content-Type: application/json'

]);

$response = curl_exec($ch);

$result = json_decode($response, true);

// Enviar con imagen (multipart)

$post = [

  'deviceId' => 'abc123',

  'to' => '51999999999',

  'message' => 'Mira esta imagen',

  'file' => new CURLFile('/ruta/foto.jpg', 'image/jpeg', 'foto.jpg')

];

curl_setopt($ch, CURLOPT_POSTFIELDS, $post);

curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $token]);

// Quitar Content-Type para que cURL lo establezca con boundary

// Enviar mensaje de texto (fetch)

const token = 'wa_tu_token_aqui';

const response = await fetch('https://tu-dominio.com/api/send', {

  method: 'POST',

  headers: {

    'Authorization': `Bearer ${token}`,

    'Content-Type': 'application/json'

  },

  body: JSON.stringify({

    deviceId: 'abc123',

    to: '51999999999',

    message: 'Hola desde JavaScript!'

  })

});

const result = await response.json();

// Con archivo (FormData)

const form = new FormData();

form.append('deviceId', 'abc123');

form.append('to', '51999999999');

form.append('message', 'Adjunto');

form.append('file', fileInput.files[0]);

await fetch('https://tu-dominio.com/api/send', {

  method: 'POST',

  headers: { 'Authorization': `Bearer ${token}` },

  body: form

});

Respuesta 200 OK (éxito)

{
  "success": true
}

Errores posibles

// 400 - Parámetros faltantes

{ "error": "deviceId y número de destino son requeridos" }

// 400 - Dispositivo no conectado

{ "error": "Dispositivo no conectado. Conecta primero el dispositivo." }

// 403 - Límite de plan

{ "error": "Has alcanzado el límite de mensajes de tu plan este mes." }

URL base

Reemplaza https://tu-dominio.com por la URL donde tienes desplegada tu API WhatAPI. Por ejemplo, en local: http://localhost:3001.