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-seperated 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

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
```
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
```
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

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
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
```

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

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

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.
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 [email protected]

then, note these down, prefixed with wa:, to them to your SPOW_TARGETS variable in your s+ow cron job
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:

rebuild when a weekly release comes out,
or rely on the weekly continuous deployment builds

to use the weekly builds without building from scratch every time,

Note

this will pull the latest binary, around 20 megabytes in size, every day. if your network or data plan may not take kindly to this, feel free to adjust the cron entry as you wish, or to one that runs once a week instead:

0 0 * * 0      bash -l -c "s+ow-whatsapp-bridge-update"

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 [email protected]

verifying a pre-built binary

Note

if you installed the bridge through an installation script, it would have already

and if the script or s+ow-whatsapp-bridge-update throws an error about failing verification, you can use the environment variable ``

TODO

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 Telegram Bridge is free and unencumbered software released into the public domain. for more information, see licences.