Skip to content

surplus on wheels: WhatsApp Bridge

WhatsApp Bridge for surplus on wheels (s+ow)

s+ow bridges are defined in a file named $HOME/.s+ow-bridges. each command in the file is run, and comma-separated target chat IDs are passed using stdin.

this bridge recognises targets prefixed with wa:.

wa:<chat id>,...

installation

from a pre-built binary

wget -O- https://surplus.joshwel.co/whatsapp.sh | sh

Note

if wget throws a 404, see backup links

building from source

on Termux

  1. clone the repository at either https://forge.joshwel.co/mark/surplus or https://github.com/markjoshwel/surplus, and navigate to src/spow-whatsapp-bridge within the cloned repository

    git clone https://forge.joshwel.co/mark/surplus
cd surplus/src/spow-whatsapp-bridge

  2. build the bridge:

    go build

    for compatibility with the documentations' instructions as-is, rename the built binary to s+ow-whatsapp-bridge

    mv spow-whatsapp-bridge s+ow-whatsapp-bridge

  3. send the built binary over to your Termux environment, and then move it into the $HOME/.local/bin/ folder. if it doesn't exist, make it with mkdir and ensure that the folder is in your PATH variable either using your .profile, .bashrc or whatever file is sourced when opening your shell

anywhere else

for usage on Termux, see if the Android NDK supports your platform

  1. grab a copy of the NDK, and extract it somewhere. navigate to <ndk folder>/toolchains/llvm/prebuilt/<your platform>/bin and look for a suitable clang executable, as it will be your CGO compiler

    m@csp:~/android-ndk-r26d/toolchains/llvm/prebuilt/linux-x86_64/bin$ ls *clang
aarch64-linux-android21-clang  aarch64-linux-android30-clang     ...
aarch64-linux-android22-clang  aarch64-linux-android31-clang
aarch64-linux-android23-clang  aarch64-linux-android32-clang
aarch64-linux-android24-clang  aarch64-linux-android33-clang
aarch64-linux-android25-clang  aarch64-linux-android34-clang
aarch64-linux-android26-clang  armv7a-linux-androideabi21-clang
aarch64-linux-android27-clang  armv7a-linux-androideabi22-clang
aarch64-linux-android28-clang  armv7a-linux-androideabi23-clang
aarch64-linux-android29-clang  armv7a-linux-androideabi24-clang

    the example output is not exhaustive and is cut short for brevity and example, do take a look at your downloaded NDK archive for what executables are available to you

    many executables are present, so choose a) what architecture you will build for (more often than not it's aarch64), and b) what target android api are you building for

    if you're building for yourself, pick an api level/version that correlates to your devices' android version. as an example, my device runs on an ARM processor (aarch64) and runs Android 14, which is api level 34. (android34) as such, i would use the aarch64-linux-android34-clang binary

  2. clone the repository at either https://forge.joshwel.co/mark/surplus or https://github.com/markjoshwel/surplus, and navigate to src/spow-whatsapp-bridge within the cloned repository

    git clone https://forge.joshwel.co/mark/surplus
cd surplus/src/spow-whatsapp-bridge

  3. build the bridge:

    CC="<path to android ndk clang executable>" GOOS=android GOARCH=arm64 CGO_ENABLED=1 go build

    for compatibility with the documentations' instructions as-is, rename the built binary to s+ow-whatsapp-bridge

    mv spow-whatsapp-bridge s+ow-whatsapp-bridge

  4. send the built binary over to your Termux environment, and then move it into the $HOME/.local/bin/ folder. if it doesn't exist, make it with mkdir and ensure that the folder is in your PATH variable either using your .profile, .bashrc or whatever file is sourced when opening your shell

post-installation setup

  1. log into WhatsApp:

    s+ow-whatsapp-bridge login

    give it a minute or two to sync your history. once the screen stops scrolling, you can safely exit with Ctrl+D or Ctrl+C.

  2. find out what chats you want the bridge to target:

    s+ow-whatsapp-bridge list

    Note

    for sending to individuals: their IDs are their internationalised phone numbers ending in @s.whatsapp.net

    example: +65 9123 4567 is 6591234567@s.whatsapp.net

    then, note these down, prefixed with wa:, to them to your SPOW_TARGETS variable in your s+ow cron job

  3. finally, add the following to your $HOME/.s+ow-bridges file:

    s+ow-whatsapp-bridge

updating

to keep updated as whatsmeow, the library the bridge depends on, has to keep updated with the WhatsApp web multidevice API, you can either:

  1. rebuild when a weekly release comes out,
  2. or rely on the weekly continuous deployment builds, if an archived build artefact is still available

an updater script was planned for pulling weekly builds without building from scratch every time, but it was not completed before the project was sunset. the archived installer is still a never-implemented stub, so there is no finished s+ow-whatsapp-bridge-update command to document.

if you need a known binary from the archived project, prefer rebuilding from source with the commands above.

usage

  • s+ow-whatsapp-bridge
    normal usage; sends latest message to wa:-prefixed targets given in stdin

  • s+ow-whatsapp-bridge login
    logs in to WhatsApp

  • s+ow-whatsapp-bridge pair-phone
    logs in to WhatsApp using a phone number

  • s+ow-whatsapp-bridge reconnect
    reconnects the client

  • s+ow-whatsapp-bridge logout
    logs out of WhatsApp

  • s+ow-whatsapp-bridge list
    lists all group chats and their IDs.

    for sending to individuals: their IDs are their internationalised phone numbers ending in @s.whatsapp.net

    example: +65 9123 4567 is 6591234567@s.whatsapp.net

verifying a pre-built binary

Note

the verification workflow was not completed before the project was sunset. the installation script in the archived repository was never filled in, and the older main branch predates this MkDocs page, so there is no older verification procedure to recover.

if you are inspecting an archived pre-built binary, the most reliable available checks are:

  1. prefer rebuilding from source with the documented Nix or Go commands

  2. compare the binary against the artefact produced by the archived continuous deployment workflow, if that artefact is still available

  3. inspect the workflow that produced it:

    .github/workflows/cd-whatsapp.yml

versioning scheme

from v2.2024.25, the bridge is now versioned with a modified calendar versioning scheme of MAJOR.YEAR.ISOWEEK, where the MAJOR version segment will be bumped with codebase changes, whereas the YEAR and ISOWEEK segments will represent the time of which the release was built at

licence

the s+ow WhatsApp Bridge is free and unencumbered software released into the public domain. for more information, see licences.