> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Recibiendo mensajes

> Manejar mensajes entrantes con webhooks, o leer chats almacenados y mensajes desde el almacenamiento del chat de GOWA.

GOWA ofrece dos maneras de recibir mensajes:

| Método | Utilízalo para |
| - | - |
| **Webhooks** (recomendado) | Reactuando a eventos en tiempo real. GOWA empuja cada evento a su URL. |
| **API de almacenamiento de chat** | Lectura del historial, recuperándose tras tiempo de inactividad, creando vistas de bandeja de entrada. |

## Webhooks

Iniciar GOWA con un webhook URL y secreto:

```bash theme={null}
./whatsapp rest --basic-auth=admin:changeme \
  --webhook=https://example.com/wa-hook \
  --webhook-secret=change-me \
  --webhook-events=message,message.ack
```

Un mensaje de texto llega como:

```json theme={null}
{
  "event": "message",
  "device_id": "628123456789@s.whatsapp.net",
  "session_id": "my-device",
  "payload": {
    "id": "3EB0C127D7BACC83D6A1",
    "chat_id": "628987654321@s.whatsapp.net",
    "from": "628987654321@s.whatsapp.net",
    "from_name": "John Doe",
    "sender_display_name": "John Doe",
    "timestamp": "2026-10-15T10:30:00Z",
    "is_from_me": false,
    "body": "Hello, how are you?"
  }
}
```

En un grupo, `chat_id` es el grupo JID (`...@g.us`) y `from` es el miembro que lo envió.

### Ejemplo: robot de respuesta automática

Verificar la firma, reconocer, luego responder a través de la API con el mismo dispositivo:

```javascript theme={null}
const express = require("express");
const crypto = require("crypto");

const GOWA = "http://localhost:3000";
const AUTH = "Basic " + Buffer.from("admin:changeme").toString("base64");
const SECRET = "change-me";

const app = express();
app.post("/wa-hook", express.raw({ type: "application/json" }), async (req, res) => {
  const sig = crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const received = req.get("X-Hub-Signature-256") || "";
  const expected = `sha256=${sig}`;
  if (!/^sha256=[0-9a-f]{64}$/.test(received) ||
      received.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const evt = JSON.parse(req.body);
  res.sendStatus(200);
  if (evt.event !== "message" || evt.payload.is_from_me) return;
  if (!evt.session_id) return;
  if (!/^hi\b/i.test(evt.payload.body || "")) return;

  const response = await fetch(`${GOWA}/send/message`, {
    method: "POST",
    headers: {
      Authorization: AUTH,
      "Content-Type": "application/json",
      "X-Device-Id": evt.session_id,          // reply from the slot that received it
    },
    body: JSON.stringify({
      phone: evt.payload.chat_id,
      message: "Hello! How can we help?",
      reply_message_id: evt.payload.id,
    }),
  });
  if (!response.ok) console.error("GOWA reply failed", response.status);
});
app.listen(8080);
```

Este ejemplo mínimo reconoce antes de enviar la respuesta. Para la producción, encolar el evento verificado de forma duradera antes de reconocerlo, deduplicar por dispositivo, chat y mensaje ID, y reintentar los envíos fallidos en su trabajador. Omitir eventos sin `session_id` o resolver el dispositivo correcto explícitamente.

Para una respuesta fija a cada mensaje, `WHATSAPP_AUTO_REPLY="We'll get back to you soon"` hace esto sin ningún código.

Ver [Webhooks](https://gowa-docs.mintlify.site/es/concepts/webhooks.md) para cada tipo de evento, campos de medios, reintentos y URLs por dispositivo.

### Maneja nuevas formas de evento

Un encabezado de álbum es un evento `message` con `payload.album` y sin cuerpo de texto. Cada imagen o video sigue como un evento multimedia separado con `payload.album_id`. Agrupa los medios con esa ID en lugar de tratar la cabecera como un mensaje perdido.

`newsletter.message` contiene las actualizaciones de los canales y no garantiza un nuevo mensaje. Las actualizaciones de contactos en línea y fuera de línea utilizan `presence`, requieren `POST /user/presence/subscribe`, y requieren que tu cliente permanezca disponible. Los cambios de nombre de grupo usan `group.info`.

Suscríbete a `device.logged_out`, `device.temporary_ban`, y `device.reachout_timelock` para distinguir las restricciones de la cuenta de las desconexiones normales. Estos eventos siempre identifican la slot con `session_id`. Vea [Webhooks](https://gowa-docs.mintlify.site/es/concepts/webhooks.md) para los campos y la configuración de presencia.

## API de almacenamiento de chat

GOWA registra chats y mensajes para cada ranura en su almacenamiento local de chat. Consulta por dispositivo:

```bash theme={null}
# list chats (filters: search, has_media, archived; paging: limit, offset)
curl -u admin:changeme -H "X-Device-Id: my-device" \
  "http://localhost:3000/chats?limit=20"

# messages in one chat (filters: start_time, end_time, media_only, is_from_me, search)
curl -u admin:changeme -H "X-Device-Id: my-device" \
  "http://localhost:3000/chat/628987654321@s.whatsapp.net/messages?limit=50"
```

Sólo los mensajes que GOWA ha visto (recibidos mientras se conecta, o entregados por la sincronización del historial de WhatsApp) están disponibles. Para pedir al teléfono un historial más antiguo en un chat, llama a `POST /chat/{chat_jid}/history` con `{"count": 50}`; los mensajes llegan de forma asincrónica.

Las encuestas son aptas para ponerse al día y vistas de bandeja de entrada. Para bots y automatizaciones, utilice webhooks.

## Descargando medios

Con auto-download en (por defecto), el webhook da una ruta bajo `statics/media/`, servido en `http://localhost:3000/statics/media/<file>`. De lo contrario, obtendrá los medios bajo demanda:

```bash theme={null}
curl -u admin:changeme -H "X-Device-Id: my-device" \
  "http://localhost:3000/message/3EB0C127D7BACC83D6A3/download?phone=628987654321@s.whatsapp.net"
```

Ver [Medios entrantes](https://gowa-docs.mintlify.site/es/examples/media-handling.md#media-entrante) para ver las condiciones bajo las cuales GOWA puede recuperar un archivo caducado.

## Leer recibos

Marca un mensaje leído (ticks azules) con `POST /message/{message_id}/read` y `{"phone": "<chat_jid>"}`, o establecer `WHATSAPP_AUTO_MARK_READ=true` para marcar cada mensaje entrante leído automáticamente.


## Related topics

- [Webhooks](https://gowa-docs.mintlify.site/es/concepts/webhooks.md)
- [Revocar mensaje](https://gowa-docs.mintlify.site/es/api-reference/message/revocar-mensaje.md)
- [Enviando mensajes](https://gowa-docs.mintlify.site/es/examples/sending-messages.md)
- [Reenviar mensaje](https://gowa-docs.mintlify.site/es/api-reference/message/reenviar-mensaje.md)
- [Mensaje estrella](https://gowa-docs.mintlify.site/es/api-reference/message/mensaje-estrella.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.