A full API around a linked WhatsApp account
GOWA connects to WhatsApp as a linked device, then exposes the session to software. Its REST API sends text, images, video, audio, documents, stickers, locations, contacts, polls, links, and forwards. It can react to, edit, revoke, delete, star, and mark messages read; list chats and contacts; manage groups; publish status; and stream events through webhooks. Version 8 added multiple WhatsApp accounts in one server with device-scoped requests.
Version 9 folds a Model Context Protocol server into the REST process. Five consolidated MCP tools cover sending, message actions, chat access, group administration, and application login or status. A connection chooses its account through X-Device-Id, with per-call override. This is unusually broad agent access: a model can send media, remove group participants, revoke messages, or log out an account. Expose only the operations and accounts you are prepared to let an agent control.
The project also connects to Chatwoot, publishes a community n8n node, and supports per-device webhooks. For a small team building an internal inbox or notification bot, that saves a considerable amount of glue.
Getting it running
Docker is the quickest route. Persist /app/storages, start the rest command on port 3000, open the dashboard, and pair a phone with the displayed QR code. Prebuilt v9.0.1 archives cover Intel and Arm macOS, 32-bit and 64-bit Windows, x86 Linux, Armv7, and Arm64. A source build needs Go 1.25.5 or newer. FFmpeg and WebP command-line tools handle image, video, and animated sticker processing.
The database stores linked-device sessions, and an optional keys database caches encryption and session material. The README warns against in-memory key storage in production because a restart can lose session state. Back up storage with the same care as an authenticated phone: it may contain message history, downloaded media, contacts, device identifiers, and credentials. Test restoration and account logout rather than assuming a copied SQLite file is sufficient.
Secure the control surface
Basic authentication supports several credentials but is optional. Set it, place the service behind TLS, and restrict it to trusted clients. The README notes that browser WebSocket connections may pass a base64 basic-auth value in the URL query because browsers cannot set the header. URLs can appear in proxy and application logs, so TLS alone does not remove credential exposure. Prefer short-lived network access and scrub query strings from logs.
MCP inherits the REST server's basic authentication. Do not expose /mcp to the internet with a shared password. Device selection also deserves authorization design: one credential that can choose any device is effectively access to every linked account.
Outgoing webhooks include an HMAC header, but the documented default secret is secret. Replace it and verify signatures before parsing events. Per-device destinations help isolate tenants, while event and JID filters reduce unnecessary data. The option to skip TLS verification is correctly marked insecure. Use a trusted private certificate authority or public certificate rather than teaching a messaging service to accept interception.
Automatic media download defaults on. That can fill storage or retain content operators did not intend to collect. Set file limits, disable downloads if unnecessary, scan untrusted files, and establish deletion rules. Chatwoot history import can use direct PostgreSQL access, which is powerful and widens the credential and schema-compatibility boundary.
Unofficial means externally fragile
The final README warning says GOWA is not affiliated with WhatsApp and advises using the official API to avoid issues. That is not boilerplate. WhatsApp can change its web protocol, session behavior, message formats, or anti-abuse enforcement without preserving this project's compatibility. GOWA depends on whatsmeow, and v9.0.1 explicitly refreshes that protocol dependency. Frequent updates are both healthy maintenance and evidence of the moving target.
Issue 777 documents server error 463 when a newly linked number tries to initiate a conversation. Its text identifies a WhatsApp server-side reach-out timelock, recommends having the recipient message first or establishing the chat on the phone, and says the API cannot bypass it. Issue 691 reports the same code appearing without a configuration change. An unofficial bridge is not a route around platform policy, especially for cold outreach.
Encryption and multi-device delivery also create edge cases. Issue 545 reports some recipients seeing a permanent “Waiting for message” state while others display the same sent message. The v9.0.1 notes add warnings for undecryptable incoming messages that were previously dropped silently. Test every critical sender and client pattern, and treat API acceptance as different from recipient-readable delivery.
MCP documentation is ahead of the release
The current README says the REST server exposes /mcp starting in v9. Issue 789 shows a narrower reality: in tagged v9.0.1, requests first return a device-required error and then a 404 after pairing because the unified MCP implementation merged after that tag. The report asks for a later release or corrected version note. Do not deploy latest blindly to solve this. Select a commit only for testing, or wait for a tagged build whose code and documentation agree.
This is a good example of why pinning matters. Major versions have changed command modes, device scoping, webhook payloads, UI packaging, and MCP transport. Read the breaking-change section and exercise clients against staging before upgrades.
Health and who should choose it
GOWA had 4,524 stars, 22 open issues and pull requests, and an MIT license when researched. The latest release, v9.0.1, arrived August 9, 2026, and the last push was August 10. Pull requests for webhooks, Chatwoot, receipts, and message types remained active on August 12. The maintenance pace is strong, and the release notes are unusually specific.
Use GOWA for experiments, home automation, or internal tools where interruption and re-pairing are acceptable. Run it with a dedicated low-value account, pinned builds, protected storage, TLS, changed secrets, verified webhooks, and narrow network access. Use the official WhatsApp Cloud API for customer support, regulated records, templates, or business messaging whose continuity and policy status matter. GOWA is the more flexible workshop; it is not the safer contract.