Skip to main content
GOWA offers two ways to receive messages:

Webhooks

Start GOWA with a webhook URL and secret:
A text message arrives as:
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:
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 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 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:
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:
See 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.