GOWA - WhatsApp Automation via REST API

Interact with WhatsApp through GOWA (Go WhatsApp Web Multi-Device) REST API for personal automation tasks.

Installation & Setup

GOWA is available at: https://github.com/aldinokemal/go-whatsapp-web-multidevice

Download

Go to the releases page and download the zip matching your OS and architecture.

Release files are named: whatsapp_VERSION_OS_ARCH.zip

Available platforms: linux (amd64/arm64/386), darwin (amd64/arm64), windows (amd64/386)

Run REST Server

./gowa rest

The server starts on http://localhost:3000 by default.

Login (First Time)

Open http://localhost:3000 in a browser, scan the QR code with WhatsApp on your phone to link the device.

Production Setup

GOWA runs in REST mode:

Base URL: http://localhost:3000
GOWA auto-connects to the device stored in the database — no X-Device-Id header needed for single-device setups.

⚠️ Important: Use REST API (port 3000) only. Do NOT use MCP mode - all schedulers and automation depend on REST.

Quick Examples

Ghost Mention (mention all without @)

curl -X POST http://localhost:3000/send/message \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "120363040656010581@g.us",
    "message": "Important announcement",
    "mentions": ["@everyone"]
  }'

Send Text Message

curl -X POST http://localhost:3000/send/message \
  -H "Content-Type: application/json" \
  -d '{"phone": "628123456789", "message": "Hello!"}'

Send Image

curl -X POST http://localhost:3000/send/image \
  -F "phone=628xxx" \
  -F "caption=Photo" \
  -F "image=@/path/to/image.jpg"

Check Status

curl http://localhost:3000/app/status | jq .

Complete API Operations

Messages

Send Text with Ghost Mention:

Endpoint: POST /send/message
Body: {"phone": "group@g.us", "message": "text", "mentions": ["@everyone"]}
@everyone mentions all members without showing @ in text ✅

Reply to Message:

Body: {"phone": "...", "message": "...", "reply_message_id": "msg_id"}

Disappearing Message:

Body: {"phone": "...", "message": "...", "duration": 86400} (seconds)

Forward Message:

Body: {"phone": "...", "message": "...", "is_forwarded": true}

Media

Send Image:

Endpoint: POST /send/image
Form data: phone, caption, image (file), compress (bool)

Send Document:

Endpoint: POST /send/file
Form data: phone, caption, file

Send Video:

Endpoint: POST /send/video
Form data: phone, caption, video, compress (bool)

Send Audio:

Endpoint: POST /send/audio
Form data: phone, audio

Send Sticker:

Endpoint: POST /send/sticker
Form data: phone, sticker (auto-converts to WebP)

Send Contact:

Endpoint: POST /send/contact
Body: {"phone": "...", "contact_name": "...", "contact_phone": "..."}

Send Location:

Endpoint: POST /send/location
Body: {"phone": "...", "latitude": 0.0, "longitude": 0.0}

Send Link:

Endpoint: POST /send/link
Body: {"phone": "...", "link": "...", "caption": "..."}

Send Poll:

Endpoint: POST /send/poll
Body: {"phone": "...", "question": "...", "options": ["A", "B"]}

Connection & Status

Get Status:

GET /app/status
Returns: {"is_connected": true, "is_logged_in": true}

Reconnect:

GET /app/reconnect

Logout:

GET /app/logout

Get QR Code (for login):

GET /app/login
Returns: PNG image (QR code to scan)

Login with Pairing Code:

GET /app/login-with-code?phone=628xxx

Groups

List My Groups:

GET /user/my/groups
Returns: {results: {data: [...]}} - groups array is at .results.data
Example: curl ... | jq '.results.data[] | {Name, JID, Members: .Participants | length}'
Max 500 groups (WhatsApp protocol limit)

Get Group Info:

GET /group/info?group_jid=xxx@g.us

Create Group:

POST /group
Body: {"name": "Group Name", "participants": ["628xxx@s.whatsapp.net"]}

Get Group Participants:

GET /group/participants?group_jid=xxx@g.us

Add Participant:

POST /group/participants
Body: {"group_jid": "...", "participants": ["628xxx@s.whatsapp.net"]}

Remove Participant:

POST /group/participants/remove
Body: {"group_jid": "...", "participants": ["628xxx@s.whatsapp.net"]}

Promote to Admin:

POST /group/participants/promote
Body: {"group_jid": "...", "participants": ["628xxx@s.whatsapp.net"]}

Demote from Admin:

POST /group/participants/demote
Body: {"group_jid": "...", "participants": ["628xxx@s.whatsapp.net"]}

Leave Group:

POST /group/leave
Body: {"group_jid": "..."}

Set Group Photo:

POST /group/photo
Form data: group_jid, photo

Set Group Name:

POST /group/name
Body: {"group_jid": "...", "name": "..."}

Set Group Description:

POST /group/topic
Body: {"group_jid": "...", "topic": "..."}

Get Invite Link:

GET /group/invite-link?group_jid=xxx@g.us

Join via Link:

POST /group/join-with-link
Body: {"link": "https://chat.whatsapp.com/..."}

Contacts & Chats

List Contacts:

GET /user/my/contacts

Get Chats:

GET /chats

Get User Info:

GET /user/info?phone=628xxx

Check if User Exists:

GET /user/check?phone=628xxx

Message Operations

Revoke/Delete Message:

POST /message/{message_id}/revoke

React to Message:

POST /message/{message_id}/reaction
Body: {"emoji": "👍"}

Edit Message:

POST /message/{message_id}/update
Body: {"message": "edited text"}

Mark as Read:

POST /message/{message_id}/read

Star Message:

POST /message/{message_id}/star

Download Media:

GET /message/{message_id}/download

Phone Number Format

User JID: 628123456789@s.whatsapp.net
Group JID: 120363040656010581@g.us
Phone only: 628123456789 (without +)

Ghost Mention Feature

How it works:

Use "mentions": ["@everyone"] in /send/message
All group members get notification
No @ symbol shown in message text (true ghost mention)
Tested and confirmed working ✅

Example for schedulers:

curl -s -X POST http://localhost:3000/send/message \
  -H 'Content-Type: application/json' \
  -d '{"phone": "120363040656010581@g.us", "message": "Reminder text", "mentions": ["@everyone"]}' | jq .

API Reference

Full OpenAPI 3.0 spec available at:

Notes

Auto-compresses images and videos before sending
Auto-converts images to WebP for stickers
Max 500 groups can be retrieved (WhatsApp protocol limit)
All media files can be sent as file upload or URL
Supports disappearing messages with custom duration
Multi-device support available via X-Device-Id header when running multiple devices
Built by @aldinokemal: https://github.com/aldinokemal/go-whatsapp-web-multidevice

gowa

Safety Notice

Copy this and send it to your AI assistant to learn