WhatsApp's chat proxy: a container that fronts WhatsApp's own servers

A chat gateway, not a VoIP relay

The repository description is unusually precise about scope: this is the proxy implementation for hosting your own infrastructure to connect to WhatsApp for chat, and VoIP is not currently supported. That single sentence removes the most common misunderstanding about the project. People looking for a way to route WhatsApp calls through their own network will not find one here.

What is here is a HAProxy configuration packaged as a container. The README describes the proxy as a gateway between you and WhatsApp's servers for the case where a direct connection is not possible, and it points readers who already have a proxy toward a WhatsApp support article for connecting it. The container generates a self-signed certificate during startup, and the expected sign of success is a line ending with `Certificate generation completed.`.

GitHub reports the primary language of this repository as Shell, which undersells what is in the tree. The top level holds `proxy/`, `cloud/`, `charts/`, and `docs/` directories alongside the usual project files, and `FAQ.md` is a first-class document that the README insists on reading before opening an issue. The shell-heavy classification fits a project whose primary interface is a set of docker commands rather than a library.

Building or pulling the image

There is a prebuilt image in Meta's DockerHub repository, and the README marks it as an update: you no longer need to build the default image unless you want to customize it.

docker pull facebook/whatsapp_proxy:latest

If you do want to build it, the sequence is clone, build the `proxy/` directory, and you have a local tag. The README is explicit that Docker needs to be set to start on boot on hosts that allow it.

git clone https://github.com/WhatsApp/proxy.git

docker build proxy/ -t whatsapp_proxy:1.0

The build step is tagged `whatsapp_proxy:1.0`, and the README's guidance is that you can substitute any tag of `whatsapp_proxy:1.0` with `facebook/whatsapp_proxy:latest` in the run command that follows. Docker Compose is listed as optional in the requirements section, but the advanced section later recommends using it for anything other than testing, since Compose handles restart strategies and port forwarding without interaction.

Nine published ports, of which two are the point

The run command publishes nine port mappings at once, which tells you the container is a multi-protocol gateway rather than a single-purpose forwarder.

docker run -it -p 80:80 -p 443:443 -p 5222:5222 -p 8080:8080 -p 8443:8443 -p 8222:8222 -p 8199:8199 -p 587:587 -p 7777:7777 whatsapp_proxy:1.0

The architecture section breaks these down. Ports 80 and 443 are standard web traffic, plain and encrypted. Port 5222 carries the Jabber protocol, which the README names as the WhatsApp default. Ports 587 and 7777 handle `*.whatsapp.net` traffic including media over HTTPS. Ports 8080, 8443, and 8222 mirror the first three but expect incoming PROXY protocol headers, version 1 or 2, which is what you want when a network load balancer sits in front and you need the client IP preserved.

Then the README does something more useful than listing ports. Under adverse network conditions it warns that this flexibility is itself a liability: a proxy instance can be uniquely identified by some of the non-standard ports, so it recommends exposing only 443 and 587 on the endpoint to get basic functionality for messages and media. That constraint applies only when the proxy is on a public IP address, not when clients reach it over a VPN or private connection. There is one more wrinkle: when using the HTTPS port 8443, port 8443 must be published publicly as port 443, because WhatsApp clients connect to 443 by default and will not find the service otherwise.

Confirming it works from a browser

The verification step is a plain HTTP request, and the port for it was in the run command: 8199. You visit `http://<host-ip>:8199` using your public IP address and you get the HAProxy statistics page. The same address works as a monitoring endpoint over time.

Two things to get right here. The README bolds the word public, because the page is not reachable from a private address without the port forwarding it describes. If the public IP is not accessible, you need to forward the ports above on whatever router or gateway you use, and the README explicitly declines to go into that because the operation is device specific.

For anything more structured than opening the page, there is an OpenMetrics endpoint at `http://<host-ip>:8199/metrics`. That is the one to point a Prometheus scraper at, and it comes free with the container rather than requiring an exporter.

Self-signed certificates and the two build arguments that matter

Ports 443 and 8443 are protected by a self-signed certificate generated when the container starts. That is a deliberate choice for a gateway that is meant to be reachable over an adverse network, and it means clients have to tolerate an untrusted certificate.

The certificate is not completely fixed, though. Two build arguments alter it, both unset by default: `SSL_DNS` takes a comma separated list of alternative hostnames, and `SSL_IP` takes a comma separated list of alternative IPs. Setting either at build time is what you would do if you front the proxy with a hostname rather than a bare IP.

docker build . --build-arg SSL_DNS=test.example.com

This is the one place where building locally earns its keep over pulling the published image, and the README frames it that way, with the customization caveat attached to the pull advice rather than presented as a separate workflow.

The chart releases the README never mentions

The repository's published releases are all Helm chart versions for Kubernetes: `whatsapp-proxy-chart-1.3.16` on 2026-08-20, then 1.3.15 and 1.3.14 on 2026-07-30. Each release carries the same one-line description, a Helm chart for Kubernetes for the WhatsApp Proxy infrastructure. The README says nothing about Helm, and nothing about Kubernetes.

Both facts are true at once, and they point at two separate audiences. The README is written for someone on a laptop or a home server who needs connectivity back, and it stops at Docker and Docker Compose. The `charts/` directory in the tree, and the chart releases on the releases page, are for someone running the same proxy inside a Kubernetes cluster. There is also a `cloud/` directory and a `docs/` directory that the README does not walk through.

If you are deploying to Kubernetes, the README is the wrong document and the chart releases are the right starting point. If you are deploying anywhere else, the reverse holds, and the Compose file the README references at `proxy/ops/docker-compose.yml` is the concrete artifact to read.

Editorial conclusion

This repository is useful for one job and only that job: restoring WhatsApp connectivity from a network that cannot reach Meta's servers directly. The build is a single docker command, the health check is a browser request to port 8199, and the port guidance is specific enough to follow without guessing. What the README does not cover is authentication, logging destinations, capacity planning, or what happens to a session that is already established when the proxy restarts. If you need those, the FAQ.md file and the external support article are the places to look. For everyone else, run the container, expose only 443 and 587, and check port 8199 before pointing a phone at it.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. WhatsApp/proxy on GitHub