A WhatsApp Web and SMS bridge for internet relay chat (IRC). (slightly less beta!)
This repo really lives at git.theta.eu.org, but it's also on GitHub as well. PRs/issues more than welcome!
What is this?
This monstrosity lets one user send and receive SMS messages through IRC, using a USB 3G modem plugged in to the server running it. It also has integrated support for WhatsApp, using the whatsappweb-rs library. Using it requires running your own IRC daemon, or having a friendly IRC daemon somewhere that lets you make large numbers of connections from one IP address.
It also has support for the InspIRCd spanning-tree protocol (v1.2), allowing you to link it to an IRC network as a pseudo-server. (This is the configuration used by the author, and is probably the most reliable way to use the bridge.)
This is also the spiritual successor of matrix-appservice-sms, in that it does the same thing as matrix-appservice-sms, except way more reliably and for a different protocol.
What can it do?
- Send and receive SMS messages through IRC, using a USB 3G modem
- Deals with concatenated (longer) SMS messages as well!
- Reasonably tolerant of modem flakiness
- Send and receive WhatsApp messages through IRC
- Deals with both one-to-one chats and groupchats
- Receive WhatsApp attachments and deal with them nicely
- Saves them in a folder somewhere for you to point a webserver at
- Manage SMS and WhatsApp contacts, allowing you to give people nice nicknames
- Lets you switch between texting and WhatsApping people
- Automatically tries to detect which method is best
- Manage the whole thing through a 'nice' IRC interface
- Imitates NickServ/ChanServ-style commands
- Links to InspIRCd as a 'services'-type pseudoserver
- Also has an undocumented and probably broken "spawn a million clients" mode, but we don't talk about that
What does it need to run?
At minimum, you need:
- An InspIRCd server, running version 2.0 or later. (3.0 supported!)
- A PostgreSQL database, running version 9 or later.
If you want WhatsApp or attachments to work, you probably also need:
- A web server, like nginx, apache, or whatever, that you can point at sms-irc's attachments directory.
- Should be accessible from the devices you want to use sms-irc with.
If you want to use the SMS stuff, you need:
- A USB 3G modem, like the Huawei E3531, or Huawei E169.
- The Huawei E3531 is the author's preferred modem, and what they've managed to get it working with.
- Other modems are available, and may well work, provided they follow the AT/Hayes command set.
Warning: sms-irc is not quite yet plug-and-play. You are expected to know a bit about how databases and web servers work in order to get everything connected together. In the future, things will be made easier.
In particular, the docker-compose setup method mentioned below lets you avoid having to worry about the IRCd. You'll still need to configure Postgres and a web server, though.
How do I set it up?
Building from source
To build this thing, you need a decently recent stable version of Rust, and development
libraries for PostgreSQL (
pacman -S postgresql-libs on Arch). Then, it's as simple as
$ cargo build --release
to build it. Configuring it takes some more effort - read
for the gory details, and rename it to
config.toml when done. Then
$ cargo run --release
should get you up and running.
Using Arch Linux AUR
You can also install
sms-irc-git from the Arch Linux AUR, and edit the example configuration file at
Run the bridge with
$ sms-irc; at present, no systemd service file is included.
Fancy docker compose method (recommended!)
If you install Docker Compose, you can get up and running pretty quickly with a pre-configured copy of sms-irc and InspIRCd 3. You'll need to define five environment variables:
SMS_DATABASE_URL: a PostgreSQL database URL to use for the database.
- This is in the form
- Keep in mind this connection will be made from within a Docker container, so your Postgres will need to be reachable that way.
SMS_ADMIN_NICK: the nickname you're going to connect as (e.g.
SMS_ATTACH_PATH: a path to somewhere on your server to store attachments (gets mounted in the container)
SMS_DL_PATH: a URL fragment for attachments, which will get at the files in
- Basically, this is all explained in
config.example.toml, but if a file is saved as
SMS_ATTACH_PATH/file.txt, sms-irc expects to hand out URLs like
SMS_DL_PATH/file.txtto IRC clients, and it's your job to make some web server make that all happen.
- For local use, you might want to just use a
file://URI pointing at your
SMS_PORT: which port you want the IRC server to listen on
You might define these, for example, with
$ export SMS_PORT=9000 $ export SMS_ATTACH_PATH=/path/to/some/folder ...
For permanent use, you probably want to use some systemd config file or whatever.
After doing that, a swift
$ docker-compose up
in the repo directory should automatically configure everything for you! Simply connect to
SMS_PORT on your local machine,
/msg sms-irc help to learn about configuration. (If you want to oper-up, try
/oper oper sms-irc.)
Simple but hard method
If you're more hardcore, you can also use the Docker image directly, for example:
$ docker run --name sms-irc \ -v PATH_TO_STORE_DATA_AND_CONFIGS_IN:/data \ -e "SMSIRC_CONFIG=/data/config.toml" \ eeeeeta/sms-irc
This helps you avoid the building part - you'll want to provide it with a
PATH_TO_STORE_DATA_AND_CONFIGS_IN where you'll put your
config.toml, and under which you'll also want to store your data directories.