• Stars
    star
    1,163
  • Rank 40,128 (Top 0.8 %)
  • Language
    Shell
  • License
    MIT License
  • Created about 2 years ago
  • Updated about 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

This repository contains the WhatsApp proxy implementation for users to host their own proxy infrastructure to connect to WhatsApp for chat (VoIP is not currently supported)

WhatsApp Chat Proxy

github CI

If you are unable to connect directly to WhatsApp, a proxy can be used as a gateway between you and our servers. To help yourself or others re-establish connection to WhatsApp, you can set up a proxy server.

If you already have a proxy to use, you can connect it to WhatsApp by following the steps in this article.

Frequently asked questions

PLEASE READ THIS BEFORE OPENING AN ISSUE We have an FAQ, which you can find here: FAQ.md

What you'll need

  1. Docker (enable Docker on startup if your host system allows)
  2. Docker compose (optional)

Setting up your proxy

UPDATE There is now a pre-built image hosted in Meta's DockerHub repository. You no longer need to build the default image (if you don't want to customize it of course).

docker pull facebook/whatsapp_proxy:latest

You can then skip down to Running the proxy and substitute any tag of whatsapp_proxy:1.0 with facebook/whatsapp_proxy:latest.

1. Clone the repository to your local machine

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

You should see a folder called proxy created in the current directory.

2. Install Docker for your system

To confirm Docker is successfully installed:

docker --version

should display a line similar to Docker version 20.10.21, build baeda1f.

2. (Optional) Install Docker compose

For Linux users, if your version of Docker doesn't come pre-installed with Docker compose, you can install a one-off version (For Linux).

# Download the pkg
sudo curl -L https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m) -o /usr/bin/docker-compose
# Enable execution of the script
sudo chmod +x /usr/bin/docker-compose

3. Build the proxy host container

Navigate to the repo directory

cd proxy

Build the proxy host container with

docker build proxy/ -t whatsapp_proxy:1.0

You should see a message similar to [+] Building 6.6s (18/18) FINISHED. The container will be compiled and tagged as whatsapp_proxy:1.0 for easy reference.

Running the proxy

Manually execute the container

You can manually execute the Docker container with the following docker command

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

You will see lines ending with Certificate generation completed.. The HAProxy is running in the background and will continue to do so until you close this process.

Check your connection

To confirm HAProxy is running, visit http://<host-ip>:8199 where <host-ip> is your public IP address. You can also use this link to monitor proxy statistics.

NOTE: If your public IP address is not accessible, you will need to enable port forwarding (for the ports above) for the router/gateway you are using. Since this operation is device-specific, we are not going to go into it in details in this doc.

If you prefer OpenMetrics output you can use http://<host-ip>:8199/metrics for monitoring HAProxy metrics.

Miscellanous

An Overview of the WhatsApp Proxy Architecture

Depending on the scenario in which you utilize your proxy, the proxy container exposes multiple ports. The basic ports may include:

  1. 80: Standard web traffic (HTTP)
  2. 443: Standard web traffic, encrypted (HTTPS)
  3. 5222: Jabber protocol traffic (WhatsApp default)
  4. 587 or 7777: *.whatsapp.net traffic including media (HTTPS)

There are also ports configured which accept incoming proxy headers (version 1 or 2) on connections. If you have a network load balancer you can preserve the client IP address if you want.

  1. 8080: Standard web traffic (HTTP) with PROXY protocol expected
  2. 8443: Standard web traffic, encrypted (HTTPS) with PROXY protocol expected
  3. 8222: Jabber protocol traffic (WhatsApp default) with PROXY protocol expected

Certificate generation for SSL encrypted ports

Ports 443 and 8443 are protected by a self-signed encryption certificate generated at container start time. There are some custom options should you wish to tweak the settings of the generated certificates

  • SSL_DNS comma separate list of alternative hostnames, no default
  • SSL_IP comma separate list of alternative IPs, no default

They can be set with commands like

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

Advanced

Automate the container lifecycle with Docker compose

Docker Compose is an automated tool to run multi-container deployments, but it also helps automate the command-line arguments necessary to run a single container. It is a YAML definition file that denotes all the settings to start up and run the container. It also has restart strategies in the event the container crashes or self-restarts. Docker Compose helps manage your container setup and necessary port forwards without user interaction. We recommend utilizing Docker Compose because you usually don’t want to manually run the container outside of testing scenarios.

We provide a sample docker-compose.yml file for you which defines a standard deployment of the proxy container.

Once Docker compose is installed, you can test your specific configuration by running Docker compose interactively with:

docker compose -f /path/to/this/repo/docker-compose.yml up

This will allow you to see the output from the build + container hosting process and check that everything is set up correctly.

When you are ready to run the container as a service, do*:

docker compose -f /path/to/this/repo/docker-compose.yml up -d

*Note the -d flag which means "daemonize" and run as a service.

To stop the container you can similarly do:

docker compose down

Automate host reboots with Docker compose

Once you have Docker compose set up, you can also automate the deployment for host reboots by utilizing a systemd service (if your hosting environment supports it).

We provide a sample docker_boot.service service definition for you which you should customize to your own environment.

To install and setup the systemd service*:

# Copy the service definition to systemd folder
cp -v docker_boot.service /etc/systemd/system/
# Enable starting the service on startup
systemctl enable docker_boot.service
# Start the service (will docker compose up the container)
systemctl start docker_boot.service
# Check container status with
docker ps

*Make sure to update the path to your specific docker-compose.yml file in the service definition docker_boot.service

Kubernetes deployment

If you would like to configure your proxy using Kubernetes, or run the Docker runtime through Kubernetes, please see our Helm chart README

Read more about other type of deployments here.

Contributors


The authors of this code are Sean Lawlor (@slawlor).

To learn more about contributing to this project, see this document.

License


This project is licensed under MIT.

More Repositories

1

stickers

This repository contains the iOS and Android sample apps and API for creating third party sticker packs for WhatsApp.
Java
2,711
star
2

waraft

An Erlang implementation of RAFT from WhatsApp
Erlang
508
star
3

eqwalizer

A type-checker for Erlang
Erlang
477
star
4

erlfmt

An automated code formatter for Erlang
Erlang
391
star
5

WhatsApp-Business-API-Setup-Scripts

The scripts related to setting up WhatsApp business API
373
star
6

erlt

Early prototype of ErlT, an experimental Erlang dialect with first-class support for static typing.
Erlang
127
star
7

StringPacks

Extracts localized strings from an Android app and stores it in a much more efficient format.
Java
124
star
8

erlfuzz

erlfuzz is a fuzzer for the Erlang ecosystem
Rust
112
star
9

WhatsApp-Nodejs-SDK

The official Meta Business Messaging WhatsApp Cloud API Node.js SDK.
TypeScript
102
star
10

erlang-language-platform

Erlang Language Platform. LSP server and CLI.
Rust
77
star
11

power_shell

Erlang shell with advanced features: evaluating non-exported functions and shortcuts for frequently used functions.
Erlang
74
star
12

tree-sitter-erlang

Tree-sitter Grammar for Erlang
C
65
star
13

WADebug

WhatsApp Debug - A command-line tool that will be used to troubleshoot installation of WhatsApp Business API.
Python
30
star
14

whatsapp-business-api-deployment-templates

This repo hosts the cloud templates which enable one-click deployment of their WhatsApp Business Platform On-Premise API on different cloud platforms with stable high messaging throughput.
HCL
24
star
15

erldist_filter

erldist_filter NIF for filtering and logging Erlang Dist Protocol messages
C
13
star
16

WhatsApp-OTP-Sample-App

Sample app that integrates with WhatsApp OTP (One-Time Password) copy code and "one-tap" autofill features. This project shows how to send and receive OTP code from WhatsApp and best practices around integration.
Swift
10
star
17

WhatsApp-Android-OTP-SDK

WhatsApp Android OTP SDK helps you integrate with one-time password solution provided by WhatsApp.It provides handy functions that simplifies the integration work.
Java
4
star
18

WhatsApp-Flows-Tools

Tools and examples to help you create WhatsApp Flows https://developers.facebook.com/docs/whatsapp/flows
1
star