Recibir mensajes WhatsApp

Como recibe WhatsBoost los mensajes

Cuando un contacto envia un mensaje a tu numero de WhatsApp vinculado, el servidor de WhatsApp envia un POST al endpoint interno /whatsapp/received de WhatsBoost. El sistema procesa el mensaje entrante y ejecuta las siguientes acciones:

1. Almacena

Guarda el mensaje en el historial de la cuenta.

2. Webhook

Envia POST a tus URLs de webhook configuradas.

3. Auto-respuesta

Evalua reglas de auto-respuesta y flujos.

4. STOP

Procesa desuscripciones automaticas.

Webhook para recibir en tu aplicacion

POST Tu URL de webhook

Configura un webhook en Dashboard > Herramientas > Webhooks con el evento whatsapp. Cada vez que llegue un mensaje a tu cuenta vinculada, WhatsBoost enviara un POST a tu URL con los datos del mensaje.

Payload del webhook

JSON — Payload de mensaje recibido

{
  "secret": "tu_webhook_secret",
  "type": "whatsapp",
  "data": {
    "id": 1234,
    "wid": "+34612345678",
    "phone": "+34698765432",
    "message": "Hola quiero reservar",
    "attachment": "https://whatsboost.net/uploads/whatsapp/received/abc123/imagen.jpg",
    "timestamp": 1711108200
  }
}

Campos del payload

Campo	Tipo	Descripcion
`secret`	`string`	Secreto del webhook configurado. Verificalo siempre para autenticar que la solicitud proviene de WhatsBoost.
`type`	`string`	Tipo de evento. Para mensajes de WhatsApp siempre es `"whatsapp"`.
`data.id`	`integer`	ID unico del mensaje.
`data.wid`	`string`	Numero de telefono de tu cuenta WhatsApp que recibio el mensaje.
`data.phone`	`string`	Numero de telefono del remitente que envio el mensaje.
`data.message`	`string`	Contenido del mensaje de texto recibido.
`data.attachment`	`string\|null`	URL del archivo adjunto descargado, o `null` si el mensaje no tiene adjuntos.
`data.timestamp`	`integer`	Marca de tiempo UNIX del momento en que se recibio el mensaje.

Importante: Tu endpoint debe responder con HTTP 200 en menos de 5 segundos. Si tu procesamiento es complejo, recibe el webhook, responde 200 inmediatamente y procesa los datos de forma asincrona.

Consultar mensajes recibidos

GET /api/get/wa.received

Obtiene el historial de mensajes recibidos en tus cuentas de WhatsApp. Requiere el permiso get_wa_received en tu API Key.

Parametros

Parametro	Tipo	Estado	Descripcion
`secret`	`string`	Obligatorio	Tu API Key con permiso `get_wa_received`.
`page`	`integer`	Opcional	Numero de pagina para la paginacion. Por defecto: `1`.
`limit`	`integer`	Opcional	Cantidad de resultados por pagina. Por defecto: `50`.

Respuesta

JSON — Respuesta de mensajes recibidos

[
  {
    "id": 1234,
    "account": "+34612345678",
    "phone": "+34698765432",
    "message": "Hola quiero reservar",
    "attachment": "https://whatsboost.net/uploads/whatsapp/received/abc123/imagen.jpg",
    "timestamp": 1711108200
  },
  {
    "id": 1235,
    "account": "+34612345678",
    "phone": "+34611222333",
    "message": "Buenos dias, necesito informacion",
    "attachment": null,
    "timestamp": 1711108500
  }
]

Consultar mensajes enviados

GET /api/get/wa.sent

Obtiene el historial de mensajes enviados desde tus cuentas de WhatsApp. Requiere el permiso get_wa_sent en tu API Key.

Parametros

Parametro	Tipo	Estado	Descripcion
`secret`	`string`	Obligatorio	Tu API Key con permiso `get_wa_sent`.
`page`	`integer`	Opcional	Numero de pagina. Por defecto: `1`.
`limit`	`integer`	Opcional	Cantidad de resultados por pagina. Por defecto: `50`.

Respuesta

JSON — Respuesta de mensajes enviados

[
  {
    "id": 5678,
    "account": "+34612345678",
    "status": 3,
    "api": 1,
    "recipient": "+34698765432",
    "message": "Tu reserva ha sido confirmada para el viernes.",
    "attachment": null,
    "created": 1711108800
  }
]

Valores de `status`

Valor	Estado	Descripcion
`1`	Pendiente	El mensaje esta en la cola esperando ser procesado.
`2`	Enviando	El mensaje esta siendo procesado por el servidor de WhatsApp.
`3`	Enviado	El mensaje fue enviado exitosamente al destinatario.
`4`	Fallido	El envio del mensaje fallo. Revisa la cuenta y el numero destinatario.

Mensajes pendientes

GET /api/get/wa.pending

Obtiene los mensajes que estan actualmente en la cola de envio. Util para monitorizar el estado de los envios en tiempo real.

Parametros

Parametro	Tipo	Estado	Descripcion
`secret`	`string`	Obligatorio	Tu API Key.

Detalle de un mensaje

GET /api/get/wa.message

Obtiene la informacion completa de un mensaje especifico, ya sea recibido o enviado.

Parametros

Parametro	Tipo	Estado	Descripcion
`secret`	`string`	Obligatorio	Tu API Key.
`id`	`integer`	Obligatorio	ID del mensaje a consultar.
`type`	`string`	Obligatorio	Tipo de mensaje: `received` (recibido) o `sent` (enviado).

Eliminar mensajes

DELETE `/api/delete/wa.received`

Elimina un mensaje recibido del historial.

Parametro	Tipo	Estado	Descripcion
`secret`	`string`	Obligatorio	Tu API Key.
`id`	`integer`	Obligatorio	ID del mensaje recibido a eliminar.

DELETE `/api/delete/wa.sent`

Elimina un mensaje enviado del historial. Tambien elimina los archivos multimedia asociados si existen.

Parametro	Tipo	Estado	Descripcion
`secret`	`string`	Obligatorio	Tu API Key.
`id`	`integer`	Obligatorio	ID del mensaje enviado a eliminar.

Atencion: La eliminacion de mensajes enviados (wa.sent) tambien elimina los archivos multimedia asociados almacenados en el servidor. Esta accion es irreversible.

Gestion de "STOP" (unsubscribe)

Cuando un contacto responde con la palabra "STOP" (o la palabra clave de desuscripcion configurada por el administrador), el sistema lo anade automaticamente a la lista de unsubscribed.

Comportamiento tras la desuscripcion:

Envio masivo: El contacto NO recibira mas mensajes de campanas ni envios masivos.
Envio individual: El envio individual directo (API o Dashboard) sigue funcionando para contactos desuscritos.
Reversion: El usuario puede eliminar manualmente un contacto de la lista de desuscritos desde Dashboard > WhatsApp > Unsubscribed.
Palabra configurable: El administrador puede cambiar la palabra de desuscripcion desde el panel de administracion.

Adjuntos recibidos

Cuando un mensaje entrante contiene archivos adjuntos (imagenes, videos, audios, documentos), WhatsBoost los descarga automaticamente y los almacena en el servidor en la ruta:

uploads/whatsapp/received/{unique_id}/{nombre_archivo}

La URL completa del adjunto se incluye en el payload del webhook en el campo data.attachment. Si el mensaje no contiene adjuntos, este campo sera null.

Formatos soportados: Imagenes (JPG, PNG, GIF, WebP), videos (MP4, 3GP), audios (OGG, MP3, AAC) y documentos (PDF, DOC, XLSX, etc.). Los archivos se almacenan en su formato original sin conversion.

Ejemplo: receptor de webhook en PHP

Este ejemplo muestra como recibir y procesar el webhook de mensajes entrantes de WhatsApp en tu servidor.

PHP — webhook_receiver.php

<?php
// Recibir el payload del webhook
$payload = json_decode(file_get_contents("php://input"), true);

// Verificar autenticidad del webhook
$my_secret = "TU_WEBHOOK_SECRET";
if (!isset($payload["secret"]) || $payload["secret"] !== $my_secret) {
    http_response_code(403);
    die("Acceso denegado");
}

// Verificar que es un evento de WhatsApp
if ($payload["type"] === "whatsapp") {
    $data = $payload["data"];

    $mensaje_id  = $data["id"];
    $cuenta_wa   = $data["wid"];
    $remitente   = $data["phone"];
    $texto       = $data["message"];
    $adjunto     = $data["attachment"]; // null si no hay
    $timestamp   = $data["timestamp"];

    // Ejemplo: guardar en base de datos o procesar
    file_put_contents("log_webhooks.txt",
        date("Y-m-d H:i:s", $timestamp) . " | De: $remitente | Msg: $texto\n",
        FILE_APPEND
    );

    // Si hay adjunto, descargarlo
    if ($adjunto) {
        $archivo = file_get_contents($adjunto);
        $nombre  = basename($adjunto);
        file_put_contents("adjuntos/$nombre", $archivo);
    }
}

// Siempre responder 200 rapidamente
http_response_code(200);
echo "OK";

Ejemplo: consultar historial con cURL

Obtener mensajes recibidos

cURL — Mensajes recibidos (pagina 1)

curl -X GET \
  "//whatsboost.netapi/get/wa.received?secret=TU_API_KEY&page=1&limit=20"

Obtener mensajes enviados

cURL — Mensajes enviados (pagina 1)

curl -X GET \
  "//whatsboost.netapi/get/wa.sent?secret=TU_API_KEY&page=1&limit=20"

Detalle de un mensaje

cURL — Detalle de mensaje recibido

curl -X GET \
  "//whatsboost.netapi/get/wa.message?secret=TU_API_KEY&id=1234&type=received"

Documentacion relacionada

Webhooks

Configuracion completa de webhooks, eventos disponibles y manejo de errores.

Auto-respuestas

Respuestas automaticas por palabra clave, regex o IA. Flujos multi-paso y chatbots.

Como recibe WhatsBoost los mensajes

1. Almacena

2. Webhook

3. Auto-respuesta

4. STOP

Webhook para recibir en tu aplicacion

Payload del webhook

Campos del payload

Consultar mensajes recibidos

Parametros

Respuesta

Consultar mensajes enviados

Parametros

Respuesta

Valores de status

Mensajes pendientes

Parametros

Detalle de un mensaje

Parametros

Eliminar mensajes

DELETE /api/delete/wa.received

DELETE /api/delete/wa.sent

Gestion de "STOP" (unsubscribe)

Comportamiento tras la desuscripcion:

Adjuntos recibidos

Ejemplo: receptor de webhook en PHP

Ejemplo: consultar historial con cURL

Obtener mensajes recibidos

Obtener mensajes enviados

Detalle de un mensaje

Documentacion relacionada

Webhooks

Auto-respuestas

Valores de `status`

DELETE `/api/delete/wa.received`

DELETE `/api/delete/wa.sent`