gowa

Original source / Raw SKILL.md

---
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": "[email protected]",
    "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": "[email protected]", "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/[email protected]`

**Create Group:**
- `POST /group`
- Body: `{"name": "Group Name", "participants": ["[email protected]"]}`

**Get Group Participants:**
- `GET /group/[email protected]`

**Add Participant:**
- `POST /group/participants`
- Body: `{"group_jid": "...", "participants": ["[email protected]"]}`

**Remove Participant:**
- `POST /group/participants/remove`
- Body: `{"group_jid": "...", "participants": ["[email protected]"]}`

**Promote to Admin:**
- `POST /group/participants/promote`
- Body: `{"group_jid": "...", "participants": ["[email protected]"]}`

**Demote from Admin:**
- `POST /group/participants/demote`
- Body: `{"group_jid": "...", "participants": ["[email protected]"]}`

**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/[email protected]`

**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:** `[email protected]`
- **Group JID:** `[email protected]`
- **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": "[email protected]", "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


---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### _meta.json

```json
{
  "owner": "aldinokemal",
  "slug": "gowa",
  "displayName": "GOWA - WhatsApp Automation",
  "latest": {
    "version": "1.4.0",
    "publishedAt": 1770686613848,
    "commit": "https://github.com/openclaw/skills/commit/d33524987bfd0d1d0d0903047d5ecef62dba0ca4"
  },
  "history": []
}

```

### references/api-endpoints.md

```markdown
# 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": "[email protected]",
  "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": ["[email protected]"]
}
```

### 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: `[email protected]` for users, `[email protected]` for groups
- Media files: can be base64 encoded or URL
- Auto-compression enabled for images and videos
- Stickers auto-converted to WebP format

```