> ## 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.

# Receiving messages

> Handle incoming messages with webhooks, or read stored chats and messages from GOWA's chat storage.

GOWA offers two ways to receive messages:

| Method | Use it for |
| - | - |
| **Webhooks** (recommended) | Reacting to events in real time. GOWA pushes each event to your URL. |
| **Chat storage API** | Reading history, catching up after downtime, building inbox views. |

## Webhooks

Start GOWA with a webhook URL and secret:

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

A text message arrives as:

```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?"
  }
}
```

In a group, `chat_id` is the group JID (`...@g.us`) and `from` is the member who sent it.

### Example: auto-reply bot

Verify the signature, acknowledge, then reply through the API with the same device:

```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);
```

This minimal example acknowledges before sending the reply. For production, enqueue the verified event durably before acknowledging it, deduplicate by device, chat, and message ID, and retry failed sends in your worker. Skip events without `session_id` or resolve the correct device explicitly.

For a fixed reply to every message, `WHATSAPP_AUTO_REPLY="We'll get back to you soon"` does this without any code.

See [Webhooks](https://gowa-docs.mintlify.site/concepts/webhooks.md) for every event type, media fields, retries and per-device URLs.

### Handle new event shapes

An album header is a `message` event with `payload.album` and no text body. Each image or video follows as a separate media event with `payload.album_id`. Group media by that ID instead of treating the header as a missing message.

`newsletter.message` contains channel counter updates and does not guarantee a new-post body. Online and offline contact updates use `presence`, require `POST /user/presence/subscribe`, and require your client to remain available. Group name changes use `group.info`.

Subscribe to `device.logged_out`, `device.temporary_ban`, and `device.reachout_timelock` to distinguish account restrictions from ordinary disconnections. These events always identify the slot with `session_id`. See [Webhooks](https://gowa-docs.mintlify.site/concepts/webhooks.md) for the fields and presence configuration.

## Chat storage API

GOWA records chats and messages for each slot in its local chat storage. Query it per device:

```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"
```

Only messages GOWA has seen (received while connected, or delivered by WhatsApp's history sync) are available. To ask the phone for older history in a chat, call `POST /chat/{chat_jid}/history` with `{"count": 50}`; the messages arrive asynchronously.

Polling is suitable for catch-up and inbox views. For bots and automations, use webhooks.

## Downloading media

With auto-download on (default), the webhook gives a path under `statics/media/`, served at `http://localhost:3000/statics/media/<file>`. Otherwise fetch the media on demand:

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

See [Incoming media](https://gowa-docs.mintlify.site/examples/media-handling.md#incoming-media) for the conditions under which GOWA can recover an expired file.

## Read receipts

Mark a message read (blue ticks) with `POST /message/{message_id}/read` and `{"phone": "<chat_jid>"}`, or set `WHATSAPP_AUTO_MARK_READ=true` to mark every incoming message read automatically.


## Related topics

- [Webhooks](https://gowa-docs.mintlify.site/concepts/webhooks.md)
- [Sending Messages](https://gowa-docs.mintlify.site/examples/sending-messages.md)
- [Revoke Message](https://gowa-docs.mintlify.site/api-reference/message/revoke-message.md)
- [Star message](https://gowa-docs.mintlify.site/api-reference/message/star-message.md)
- [Unstar message](https://gowa-docs.mintlify.site/api-reference/message/unstar-message.md)


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