whatsmeow: a Go library for the WhatsApp web multidevice API

A library with no releases and a README shorter than the file list

The README is about forty lines long and most of it is a feature checklist. There is no install section, no quick start, no version table. Installation is implied by the module path in the `go.mod` manifest, which is not on GitHub at all:

module go.mau.fi/whatsmeow

go 1.26.0

toolchain go1.27.1

That module path is hosted on the personal infrastructure of the maintainer rather than on a package host or a vanity import service tied to the repository. It works, because `go get go.mau.fi/whatsmeow` fetches the module proxy, but it means the module you depend on and the repository you read are two separate things that a maintainer has to keep pointed at each other.

The release list is empty. No tags, no GitHub releases, no changelog entries. For a library at 7,385 stars with 1,210 forks, that is unusual, and it has a concrete consequence: there is no version to pin. A consumer cannot say which commit they tested against unless they record the pseudo-version themselves.

The tree, by contrast, is large and specific. Alongside the obvious `client.go`, `send.go`, `message.go` and `group.go`, there are `pair-code.go`, `pair-passkey.go`, `qrchan.go`, `notification.go`, `push.go`, `keepalive.go`, `newsletter.go`, `presence.go`, `privacysettings.go` and `reportingtoken.go`, plus a `reportingfields.json` at the root, and directories for `socket/`, `store/`, `types/`, `binary/`, `proto/` and `appstate/`. That gap between a forty-line README and a tree this specific is the main thing to understand about the project before you use it.

What the README promises and what the tree quietly adds

The feature list covers sending and receiving messages in private chats and groups, group management with change events, joining via invite messages and invite links, typing notifications, delivery and read receipts, app state such as the contact list and chat pin or mute status, retry receipts when decryption fails, and status messages, which it marks experimental with a warning that they may not work for large contact lists.

That list is accurate but incomplete in a way that matters if you are evaluating scope. Nothing in the README mentions newsletters, and yet `newsletter.go` sits in the tree. Nothing mentions passkey or key-pair device linking, and yet `pair-passkey.go` and `pair-code.go` are separate files. Nothing mentions presence, and `presence.go` exists. Nothing about privacy settings or reporting tokens, both of which have their own files.

So the pattern is that new capability gets a file and a godoc comment, and the README checklist gets updated only sometimes. Reading godoc rather than the README will give you a truer picture of the current state of the library.

There is also a small internal tension worth naming. The list of things not yet implemented includes calls, and the README is straightforward about it, saying in one line that calls are unsupported and that broadcast list messages are not supported on WhatsApp web either. Yet the tree contains `call.go`. The file almost certainly exists to receive and represent incoming call events rather than to place calls, and the two facts are consistent, but the naming collision is enough to mislead someone browsing the repository for the first time.

Why the dependency list looks like a server library

The direct dependencies in the manifest explain a lot about the design. There is `go.mau.fi/libsignal`, which is the Signal protocol implementation that WhatsApp's own client also relies on for its cryptographic layer. There is `github.com/beeper/argo-go`, which is the Argo tunnel client, used for connecting through WhatsApp's companion-device path rather than through a public websocket endpoint. `github.com/coder/websocket` handles the socket, `github.com/rs/zerolog` handles logging, and `golang.org/x/crypto` and `google.golang.org/protobuf` do what you would expect.

Two things follow from that list. First, this is not a REST wrapper. Connecting a device requires the noise handshake, the Signal key exchange and a persistent authenticated socket, which is why `handshake.go`, `cstoken.go` and `tctoken.go` are separate files holding the different token types.

Second, the language version requirement is aggressive. The manifest declares `go 1.26.0` with a toolchain line pointing at go1.27.1. That is not a constraint you can ignore the way you can ignore an old library's style preferences: a build environment on an older Go release will refuse the module rather than degrade. It also means the library is effectively tracking the newest Go release, so a project that has pinned its toolchain for other reasons will need to reconcile the two before it can depend on whatsmeow.

Where to actually learn the API

The README points at the godoc page for methods and event types and at a simple example at the top of the package documentation. It also routes protocol questions to a dedicated category on GitHub Discussions, and says explicitly that this is where to ask about things like how to send a specific type of message.

That routing is a signal about the shape of the project. Usage questions have answers in the documentation; protocol questions have answers in discussion threads, because they are the kind of thing that changes when WhatsApp changes its wire format. A question such as how to send a particular message type is not a documentation gap, it is a research task.

Chat is on Matrix, in a room named after the project on a maunium.net homeserver. For a library this dependent on a proprietary protocol, that is where bug reports and reverse engineering notes tend to accumulate, and it is a different audience from a normal Go dependency.

The store directory is the other place worth reading before you commit. A protocol client needs somewhere to put device identity keys, prekeys and session state, and libraries usually make that an interface so the host application chooses the database. The separation of `store/` from the rest of the tree suggests that is what happens here, and it is the interface you will implement first if you are building anything long-lived.

What to weigh before choosing it

The honest framing is that this library talks to a service that does not offer this interface. WhatsApp web is not a documented API, the multidevice protocol is reverse engineered, and the terms of service around unofficial clients are not friendly to automation. Search interest around this project is heavy on bans and on which language the library exists in, which is a reasonable proxy for what practitioners are actually worried about.

Against that, the technical case is real. There is no official WhatsApp API for personal accounts, so an unofficial client is the only route to multi-device messaging from Go. The feature list covers the operations most automation actually needs, including receipts, app state and group management, and the retry-receipt handling for decryption failures is the kind of detail that only exists in a client that has been used against real traffic for a long time.

The library is not archived and the last push was on 2026-09-21, so it is being worked on. But it ships without tags, so you are tracking a moving branch, and the operational consequence of a protocol change lands on you rather than on a version bump you could have pinned. If you need this, read the store interface and the pairing code first, pin a commit explicitly in your own build, and keep your own abstraction layer between your application and the library so a breaking change is a day of work rather than a rewrite.

Editorial conclusion

whatsmeow is a serious protocol implementation rather than a thin wrapper, and the file layout is the proof: protobuf definitions, a socket layer, a store interface and media retry handling are all present, none of which you would write if you were just calling an HTTP API. What you are taking on is an unofficial client: there is no compatibility guarantee from WhatsApp, there are no tagged releases, and the pairing and device identity code is where breakage lands first. The README is honest about what is missing, calls and broadcast lists, so treat its feature list as the contract. Read the source before you commit, start from the example on the package documentation page, and keep the go directive in mind if your build environment is older than the library.

Frequently asked questions

Official sources

1. Issues
2. License: MPL-2.0
3. Project website
4. README
5. tulir/whatsmeow on GitHub