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:
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 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
1---2name: gowa3description: Interact with WhatsApp via GOWA (Go WhatsApp Web Multi-Device) REST API for personal automation. Supports sending messages with ghost mentions (@everyone), images, documents, group management, and more. Always use REST mode (http://localhost:3000) for production.4---5
6# GOWA - WhatsApp Automation via REST API
7
8Interact with WhatsApp through GOWA (Go WhatsApp Web Multi-Device) REST API for personal automation tasks.
9
10## Installation & Setup
11
12GOWA is available at: https://github.com/aldinokemal/go-whatsapp-web-multidevice
13
14### Download
15
16Go to the [releases page](https://github.com/aldinokemal/go-whatsapp-web-multidevice/releases) and download the zip matching your OS and architecture.
17
18Release files are named: `whatsapp_VERSION_OS_ARCH.zip`
19
20Available platforms: `linux` (amd64/arm64/386), `darwin` (amd64/arm64), `windows` (amd64/386)
21
22### Run REST Server
23
24```bash
25./gowa rest
26```
27
28The server starts on `http://localhost:3000` by default.
29
30### Login (First Time)
31
32Open `http://localhost:3000` in a browser, scan the QR code with WhatsApp on your phone to link the device.
33
34## Production Setup
35
36**GOWA runs in REST mode:**
37- Base URL: `http://localhost:3000`
38- GOWA auto-connects to the device stored in the database — no `X-Device-Id` header needed for single-device setups.
39
40**⚠️ Important:** Use REST API (port 3000) only. Do NOT use MCP mode - all schedulers and automation depend on REST.
41
42## Quick Examples
43
44### Ghost Mention (mention all without @)
45```bash
46curl -X POST http://localhost:3000/send/message \
47 -H "Content-Type: application/json" \
48 -d '{
49 "phone": "120363040656010581@g.us",
50 "message": "Important announcement",
51 "mentions": ["@everyone"]
52 }'
53```
54
55### Send Text Message
56```bash
57curl -X POST http://localhost:3000/send/message \
58 -H "Content-Type: application/json" \
59 -d '{"phone": "628123456789", "message": "Hello!"}'
60```
61
62### Send Image
63```bash
64curl -X POST http://localhost:3000/send/image \
65 -F "phone=628xxx" \
66 -F "caption=Photo" \
67 -F "image=@/path/to/image.jpg"
68```
69
70### Check Status
71```bash
72curl http://localhost:3000/app/status | jq .
73```
74
75## Complete API Operations
76
77### Messages
78
79**Send Text with Ghost Mention:**
80- Endpoint: `POST /send/message`
81- Body: `{"phone": "group@g.us", "message": "text", "mentions": ["@everyone"]}`
82- **@everyone** mentions all members without showing @ in text ✅
83
84**Reply to Message:**
85- Body: `{"phone": "...", "message": "...", "reply_message_id": "msg_id"}`
86
87**Disappearing Message:**
88- Body: `{"phone": "...", "message": "...", "duration": 86400}` (seconds)
89
90**Forward Message:**
91- Body: `{"phone": "...", "message": "...", "is_forwarded": true}`
92
93### Media
94
95**Send Image:**
96- Endpoint: `POST /send/image`
97- Form data: `phone`, `caption`, `image` (file), `compress` (bool)
98
99**Send Document:**
100- Endpoint: `POST /send/file`
101- Form data: `phone`, `caption`, `file`
102
103**Send Video:**
104- Endpoint: `POST /send/video`
105- Form data: `phone`, `caption`, `video`, `compress` (bool)
106
107**Send Audio:**
108- Endpoint: `POST /send/audio`
109- Form data: `phone`, `audio`
110
111**Send Sticker:**
112- Endpoint: `POST /send/sticker`
113- Form data: `phone`, `sticker` (auto-converts to WebP)
114
115**Send Contact:**
116- Endpoint: `POST /send/contact`
117- Body: `{"phone": "...", "contact_name": "...", "contact_phone": "..."}`
118
119**Send Location:**
120- Endpoint: `POST /send/location`
121- Body: `{"phone": "...", "latitude": 0.0, "longitude": 0.0}`
122
123**Send Link:**
124- Endpoint: `POST /send/link`
125- Body: `{"phone": "...", "link": "...", "caption": "..."}`
126
127**Send Poll:**
128- Endpoint: `POST /send/poll`
129- Body: `{"phone": "...", "question": "...", "options": ["A", "B"]}`
130
131### Connection & Status
132
133**Get Status:**
134- `GET /app/status`
135- Returns: `{"is_connected": true, "is_logged_in": true}`
136
137**Reconnect:**
138- `GET /app/reconnect`
139
140**Logout:**
141- `GET /app/logout`
142
143**Get QR Code (for login):**
144- `GET /app/login`
145- Returns: PNG image (QR code to scan)
146
147**Login with Pairing Code:**
148- `GET /app/login-with-code?phone=628xxx`
149
150### Groups
151
152**List My Groups:**
153- `GET /user/my/groups`
154- Returns: `{results: {data: [...]}}` - groups array is at `.results.data`
155- Example: `curl ... | jq '.results.data[] | {Name, JID, Members: .Participants | length}'`
156- Max 500 groups (WhatsApp protocol limit)
157
158**Get Group Info:**
159- `GET /group/info?group_jid=xxx@g.us`
160
161**Create Group:**
162- `POST /group`
163- Body: `{"name": "Group Name", "participants": ["628xxx@s.whatsapp.net"]}`
164
165**Get Group Participants:**
166- `GET /group/participants?group_jid=xxx@g.us`
167
168**Add Participant:**
169- `POST /group/participants`
170- Body: `{"group_jid": "...", "participants": ["628xxx@s.whatsapp.net"]}`
171
172**Remove Participant:**
173- `POST /group/participants/remove`
174- Body: `{"group_jid": "...", "participants": ["628xxx@s.whatsapp.net"]}`
175
176**Promote to Admin:**
177- `POST /group/participants/promote`
178- Body: `{"group_jid": "...", "participants": ["628xxx@s.whatsapp.net"]}`
179
180**Demote from Admin:**
181- `POST /group/participants/demote`
182- Body: `{"group_jid": "...", "participants": ["628xxx@s.whatsapp.net"]}`
183
184**Leave Group:**
185- `POST /group/leave`
186- Body: `{"group_jid": "..."}`
187
188**Set Group Photo:**
189- `POST /group/photo`
190- Form data: `group_jid`, `photo`
191
192**Set Group Name:**
193- `POST /group/name`
194- Body: `{"group_jid": "...", "name": "..."}`
195
196**Set Group Description:**
197- `POST /group/topic`
198- Body: `{"group_jid": "...", "topic": "..."}`
199
200**Get Invite Link:**
201- `GET /group/invite-link?group_jid=xxx@g.us`
202
203**Join via Link:**
204- `POST /group/join-with-link`
205- Body: `{"link": "https://chat.whatsapp.com/..."}`
206
207### Contacts & Chats
208
209**List Contacts:**
210- `GET /user/my/contacts`
211
212**Get Chats:**
213- `GET /chats`
214
215**Get User Info:**
216- `GET /user/info?phone=628xxx`
217
218**Check if User Exists:**
219- `GET /user/check?phone=628xxx`
220
221### Message Operations
222
223**Revoke/Delete Message:**
224- `POST /message/{message_id}/revoke`
225
226**React to Message:**
227- `POST /message/{message_id}/reaction`
228- Body: `{"emoji": "👍"}`
229
230**Edit Message:**
231- `POST /message/{message_id}/update`
232- Body: `{"message": "edited text"}`
233
234**Mark as Read:**
235- `POST /message/{message_id}/read`
236
237**Star Message:**
238- `POST /message/{message_id}/star`
239
240**Download Media:**
241- `GET /message/{message_id}/download`
242
243## Phone Number Format
244
245- **User JID:** `628123456789@s.whatsapp.net`
246- **Group JID:** `120363040656010581@g.us`
247- **Phone only:** `628123456789` (without +)
248
249## Ghost Mention Feature
250
251**How it works:**
252- Use `"mentions": ["@everyone"]` in `/send/message`
253- All group members get notification
254- **No @ symbol shown in message text** (true ghost mention)
255- Tested and confirmed working ✅
256
257**Example for schedulers:**
258```bash
259curl -s -X POST http://localhost:3000/send/message \
260 -H 'Content-Type: application/json' \
261 -d '{"phone": "120363040656010581@g.us", "message": "Reminder text", "mentions": ["@everyone"]}' | jq .
262```
263
264## API Reference
265
266Full OpenAPI 3.0 spec available at:
267- OpenAPI: https://raw.githubusercontent.com/aldinokemal/go-whatsapp-web-multidevice/refs/heads/main/docs/openapi.yaml
268- GitHub: https://github.com/aldinokemal/go-whatsapp-web-multidevice
269
270## Notes
271
272- Auto-compresses images and videos before sending
273- Auto-converts images to WebP for stickers
274- Max 500 groups can be retrieved (WhatsApp protocol limit)
275- All media files can be sent as file upload or URL
276- Supports disappearing messages with custom duration
277- Multi-device support available via `X-Device-Id` header when running multiple devices
278- Built by @aldinokemal: https://github.com/aldinokemal/go-whatsapp-web-multidevice
modbender