Skill: aldinokemal/gowa (version 1.4.0)

--- name: gowa description: 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. user-invocable: true command-dispatch: model --- # 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](https://github.com/aldinokemal/go-whatsapp-web-multidevice/releases) 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 ```bash ./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 @) ```bash curl -X POST http://localhost:3000/send/message \ -H "Content-Type: application/json" \ -d '{ "phone": "[REDACTED_SECRET]", "message": "Important announcement", "mentions": ["@everyone"] }' ``` ### Send Text Message ```bash curl -X POST http://localhost:3000/send/message \ -H "Content-Type: application/json" \ -d '{"phone": "628123456789", "message": "Hello!"}' ``` ### Send Image ```bash curl -X POST http://localhost:3000/send/image \ -F "phone=628xxx" \ -F "caption=Photo" \ -F "image=@/path/to/image.jpg" ``` ### Check Status ```bash curl http://localhost:3000/app/status | jq . ``` ## Complete API Operations ### Messages **Send Text with Ghost Mention:** - Endpoint: `POST /send/message` - Body: `{"phone": "[REDACTED_SECRET]", "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=[REDACTED_SECRET]` **Create Group:** - `POST /group` - Body: `{"name": "Group Name", "participants": ["[REDACTED_SECRET]"]}` **Get Group Participants:** - `GET /group/participants?group_jid=[REDACTED_SECRET]` **Add Participant:** - `POST /group/participants` - Body: `{"group_jid": "...", "participants": ["[REDACTED_SECRET]"]}` **Remove Participant:** - `POST /group/participants/remove` - Body: `{"group_jid": "...", "participants": ["[REDACTED_SECRET]"]}` **Promote to Admin:** - `POST /group/participants/promote` - Body: `{"group_jid": "...", "participants": ["[REDACTED_SECRET]"]}` **Demote from Admin:** - `POST /group/participants/demote` - Body: `{"group_jid": "...", "participants": ["[REDACTED_SECRET]"]}` **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=[REDACTED_SECRET]` **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:** `[REDACTED_SECRET]` - **Group JID:** `[REDACTED_SECRET]` - **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:** ```bash curl -s -X POST http://localhost:3000/send/message \ -H 'Content-Type: application/json' \ -d '{"phone": "[REDACTED_SECRET]", "message": "Reminder text", "mentions": ["@everyone"]}' | jq . ``` ## API Reference Full OpenAPI 3.0 spec available at: - OpenAPI: https://raw.githubusercontent.com/aldinokemal/go-whatsapp-web-multidevice/refs/heads/main/docs/openapi.yaml - GitHub: https://github.com/aldinokemal/go-whatsapp-web-multidevice ## 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

path: references/api-endpoints.md
content: # GOWA API Endpoints Reference

Base URL: `http://localhost:3000` (default)

## Authentication
- No authentication required by default
- Optional Basic Auth (if GOWA started with `--basic-auth=user:password`)
  - Header: `Authorization: Basic <base64(user:password)>`

## Multi-Device Support
All device-scoped API calls require either:
- `X-Device-Id` header, or
- `device_id` query parameter

If only one device is registered, it will be used as default.

## Core Endpoints

### Device Management
- `GET /devices` - List all registered devices
- `POST /devices` - Add new device
- `GET /devices/:device_id` - Get device info
- `DELETE /devices/:device_id` - Remove device
- `GET /devices/:device_id/login` - Login with QR code
- `POST /devices/:device_id/login/code` - Login with pairing code
- `POST /devices/:device_id/logout` - Logout device
- `POST /devices/:device_id/reconnect` - Reconnect device
- `GET /devices/:device_id/status` - Get device connection status

### Legacy App Endpoints (backward compatibility)
- `GET /app/login` - Login with QR (scan)
- `GET /app/login-with-code` - Login with pairing code
- `GET /app/logout` - Logout
- `GET /app/reconnect` - Reconnect
- `GET /app/devices` - List devices
- `GET /app/status` - Connection status

### Send Messages
- `POST /send/message` - Send text message
  - Supports mentions: `@628xxx` in text
  - Ghost mentions: pass phone numbers in `mentions` field
  - Mention all: use `@everyone` keyword
- `POST /send/image` - Send image (auto-compress)
- `POST /send/file` - Send document
- `POST /send/video` - Send video (auto-compress)
- `POST /send/sticker` - Send sticker (auto-convert to WebP)
- `POST /send/contact` - Send contact card
- `POST /send/link` - Send link with preview
- `POST /send/location` - Send location
- `POST /send/poll` - Send poll/vote
- `POST /send/audio` - Send audio
- `POST /send/presence` - Send presence (available/unavailable)
- `POST /send/chat-presence` - Send typing indicator

### Message Operations
- `POST /message/:message_id/revoke` - Delete for everyone
- `POST /message/:message_id/reaction` - React to message
- `POST /message/:message_id/delete` - Delete for me
- `POST /message/:message_id/update` - Edit message
- `POST /message/:message_id/read` - Mark as read
- `POST /message/:message_id/star` - Star message
- `POST /message/:message_id/unstar` - Unstar message
- `GET /message/:message_id/download` - Download media

### User Info
- `GET /user/info` - Get user info
- `GET /user/avatar` - Get user avatar
- `POST /user/avatar` - Change avatar
- `POST /user/pushname` - Change display name
- `GET /user/my/groups` - List my groups (max 500)
- `GET /user/my/newsletters` - List my newsletters
- `GET /user/my/privacy` - Get privacy settings
- `GET /user/my/contacts` - List contacts
- `GET /user/check` - Check if user exists
- `GET /user/business-profile` - Get business profile

### Groups
- `POST /group` - Create group
- `POST /group/join-with-link` - Join via invite link
- `GET /group/info-from-link` - Get group info from link
- `GET /group/info` - Get group info
- `POST /group/leave` - Leave group
- `GET /group/participants` - List participants
- `POST /group/participants` - Add participants
- `POST /group/participants/remove` - Remove participant
- `POST /group/participants/promote` - Promote to admin
- `POST /group/participants/demote` - Demote from admin
- `GET /group/participants/export` - Export participants (CSV)
- `GET /group/participant-requests` - List join requests
- `POST /group/participant-requests/approve` - Approve join request
- `POST /group/participant-requests/reject` - Reject join request
- `POST /group/photo` - Set group photo
- `POST /group/name` - Set group name
- `POST /group/locked` - Lock group info (admin only edit)
- `POST /group/announce` - Set announcement mode
- `POST /group/topic` - Set group description
- `GET /group/invite-link` - Get invite link

### Chats
- `GET /chats` - Get chat list
- `GET /chat/:chat_jid/messages` - Get chat messages
- `POST /chat/:chat_jid/label` - Label chat
- `POST /chat/:chat_jid/pin` - Pin chat
- `POST /chat/:chat_jid/archive` - Archive chat
- `POST /chat/:chat_jid/disappearing` - Set disappearing messages

### Newsletter
- `POST /newsletter/unfollow` - Unfollow newsletter

## Common Request Formats

### Send Text Message
```json
{
  "phone": "628xxx",
  "message": "Hello everyone!",
  "mentions": ["@everyone"]
}
```

**Ghost Mention (mention all without showing @ in text):**
```json
{
  "phone": "[REDACTED_SECRET]",
  "message": "Important announcement",
  "mentions": ["@everyone"]
}
```
- Use `"@everyone"` to mention all group members
- Members get notification but no @ shown in message text
- Tested and working in both REST and MCP modes

**Regular Mentions (shows @phone in text):**
```json
{
  "phone": "628xxx",
  "message": "Hello @628xxx",
  "mentions": ["[REDACTED_SECRET]"]
}
```

### Send Document
```json
{
  "phone": "628xxx",
  "caption": "Document caption",
  "file": "base64_encoded_file_or_url"
}
```

### Get QR Code
```
GET /app/login
Returns: PNG image (QR code)
```

### List Groups
```
GET /user/my/groups
Returns: JSON array of group objects
```

## Response Format
Success:
```json
{
  "code": 200,
  "message": "Success",
  "data": {...}
}
```

Error:
```json
{
  "code": 400,
  "message": "Error description"
}
```

## Notes
- Phone numbers format: international without `+` (e.g., `628123456789`)
- JID format: `[REDACTED_SECRET]` for users, `[REDACTED_SECRET]` for groups
- Media files: can be base64 encoded or URL
- Auto-compression enabled for images and videos
- Stickers auto-converted to WebP format


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)