Cobalt, an unofficial WhatsApp client library for the JVM

Two transports behind one shared message model

Cobalt turns a JVM application into a WhatsApp client, and it reaches WhatsApp in two very different ways that sit behind one message model. The Linked client is a clean-room reimplementation of the real WhatsApp Web, Desktop and Mobile apps. No browser, no Selenium, no bridge process. The Cloud client is the opposite in spirit: it drives Meta's hosted WhatsApp Cloud API over plain HTTPS and ships a built-in webhook server for inbound traffic.

The library is published as com.github.auties00/cobalt-lib, and the project description calls it a standalone, fully-featured WhatsApp Web and Mobile API for Java and Kotlin. The shared model is the part that makes the design worth a look. Application code can be written against one set of domain objects and then pointed at either backend, which matters when a team is weighing a linked transport for its own use against a hosted channel for customer traffic. The repository is laid out as a multi-module Maven build, with modules/ holding the library and tools/ holding the extraction and agent tooling, and it ships a Maven wrapper at the top level.

The linked transport talks to a protocol WhatsApp does not support

The Linked client speaks to WhatsApp's private protocol through a reverse-engineered transport, and the project does not soften that. The documentation states plainly that WhatsApp does not support third-party clients, so this transport may breach its Terms of Service, lead to account restrictions, or stop working at any time. It also draws a line between two kinds of use: good-faith use of your own account carries little risk, while sending unsolicited or automated bulk messages, especially from new numbers, is exactly what WhatsApp's anti-spam systems act on. For commercial messaging the project points readers at the official Cloud API.

That is the sharpest constraint in the whole codebase. The most capable mode is also the mode most likely to get a phone number restricted, and the failure is not a clean error, it is a number that quietly stops working. Any adoption plan should decide early which client carries production traffic, because that choice sets both the reliability of the connection and the exposure of the number sitting behind it. Cobalt also carries an explicit disclaimer that it is independent, unofficial, and not affiliated with, authorised by, or endorsed by WhatsApp LLC or Meta Platforms.

Deterministic extractors keep the domain model aligned with WhatsApp Web

A large share of Cobalt's accuracy comes from tooling rather than from hand-writing protocol code. The repository ships deterministic extractors that run against the real WhatsApp Web client, so they can be regenerated whenever WhatsApp publishes a new revision. The protobuf extractor pulls every protobuf message and enum out of WhatsApp Web's JavaScript chunks and WASM binaries into a single whatsapp.proto, which serves as the reference spec for the hand-written domain classes under modules/model. A second extractor handles AB Props, the A/B feature flag definitions with their name, type and default value, and regenerates the ABProp constants in that same module.

A third dumps the spec of every GraphQL operation, including id, kind, variables and transport, from the persisted-query layer, and the typed request and response models in modules/lib are validated against it. A fourth regenerates the per-event Java classes for the WAM telemetry runtime, consumed by the modules/wam-core annotation processor. Each extractor is a Node project, and the documented workflow is identical for all of them:

npm install
npm run build
npm start

Run that sequence inside the extractor directory and the generated sources are refreshed. The practical effect is that a wire format change can be absorbed by regenerating instead of patching Java by hand, which is the only sane way to keep a reimplementation of a private protocol current.

The MCP server gives agents a view of the real client

Reverse engineering across Web, Desktop, Mobile and the Cloud API is not a skill most contributors have, and the project acknowledges that directly. To lower the barrier it ships the Cobalt MCP server under tools/web/mcp-server. The server is built rather than installed, and the build pulls a Chromium binary through Playwright:

cd tools/web/mcp-server
npm install
npx playwright install chromium
npm run build

After the build the server is started from the same directory:

cd tools/web/mcp-server
npm start

An agent whose working directory is Cobalt's should then recognise the MCP server automatically.

For contributors this is the difference between guessing and observing. It also underpins the validation workflow described in the next section, since the live WhatsApp runtime has to be reachable somehow for any diff to be meaningful. Contributors are told they do not need to be reverse engineers to help, and the priority order is stated plainly: performance is an absolute priority, with full feature coverage and stability alongside it. Contributions are welcome from anyone, including machine-generated code, provided the person opening the pull request stands behind every line, and no AI-generated commit messages, issue bodies, pull request descriptions, discussion posts or review comments.

The /validate command diffs Cobalt's output against the live runtime

Cobalt ships a /validate command for agentic coding tools, described in .claude/commands/validate.md. It orchestrates a fleet of agents whose purpose is to try to prove that Cobalt implements every WhatsApp feature correctly, and it works on two levels. Source parity checks each Cobalt module against the behaviour of its WhatsApp counterpart. Observable parity is the more demanding one: the stanzas, events and requests Cobalt produces for a given input are diffed against what the real WhatsApp runtime produces for the same input, captured live through the MCP server.

The project calls this highly experimental, and it is fair to treat it that way. Still, the idea addresses a real weakness in protocol work. A reimplementation of a private protocol normally rests on unit tests against captured fixtures, and fixtures drift away from the live client without anyone noticing until a real message stops being delivered. Diffing observable behaviour against a live client turns that drift into a visible failure. It is also a fair proxy for how Cobalt is developed as a whole, with extractor code and validator code in the same repository, and the human reviewer explicitly in the loop.

Maven Central packaging, no releases, and an API that is still moving

The library is published on Maven Central under the artifact com.github.auties00/cobalt-lib, with generated API documentation published on javadoc.io, and the project also links a JitPack route for consumers who prefer to build from source. The top level of the repository carries mvnw and mvnw.cmd next to pom.xml, so a Maven wrapper is present and the build does not depend on a locally installed Maven.

Three facts matter when planning around Cobalt. The API is pre-1.0, and the project warns that breaking changes are expected between releases until the API is frozen, so version pinning decisions have to assume the surface will move. There are no GitHub releases at all, which means release history has to be read from Maven Central rather than from release notes, and there is no changelog to consult when a behaviour changes. The licence field on the repository says MIT, which is permissive enough for both commercial and personal use, though the disclaimers in the documentation are worth reading carefully because they concern the WhatsApp Terms of Service rather than the licence grant. The last push was on 2026-07-15, and the repository is not archived.

Why the Cloud API is the sensible default for business traffic

Cobalt's own guidance gives the clearest comparison available, because the project itself holds both approaches. The linked transport is a reimplementation of the real apps talking to a private protocol, which buys full feature coverage and direct access but runs against the Terms of Service and carries the risk of account restrictions. The Cloud client speaks plain HTTPS to Meta's hosted API, with a built-in webhook server for inbound traffic, which is a supported channel with none of the third-party client exposure.

That difference is not a matter of speed or throughput, it is a matter of whose rules govern the connection. Meta's hosted path is the same path the project's disclaimer tells commercial users to prefer, and the Cobalt Cloud client is a convenience layer on top of it, not a replacement. Choosing a different route entirely, driving a real WhatsApp Web session through a browser with Selenium, gives up on the clean-room claim and brings a browser into the deployment, which is exactly what the linked client was built to avoid. For a JVM team that needs Webhooks and inbound handling today, the Cloud client inside Cobalt is the path with the fewest unknowns, and the linked transport is the path to evaluate separately.

Editorial conclusion

Cobalt fits engineers who need a real WhatsApp client inside a JVM service and can accept an unofficial transport, and it does not fit teams that need a supported commercial channel. Before adopting it, check whether the linked transport or the Cloud client will carry the traffic, read the pre-1.0 warning about breaking changes, and confirm the version on Maven Central matches the code you plan to write against.

Frequently asked questions

Official sources

1. Auties00/Cobalt on GitHub
2. Issues
3. License: MIT
4. README