eeeeeta/sms-irc repository overview

⁠sms-irc

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 config.example.toml⁠ 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 /etc/sms-irc.conf.

Run the bridge with $ sms-irc; at present, no systemd service file is included.

⁠Fancy docker compose method (recommended!)

Good news! We have a Docker⁠ container for you, as eeeeeta/sms-irc⁠ on Docker Hub.

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 postgresql://user[:password]@host/dbname.
  • 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. eeeeeta)
• 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 SMS_ATTACH_PATH
  • 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.txt to 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_ATTACH_PATH.
• 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, join #smsirc, and /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.

⁠Aaaagh what, this is all very confusing and I have questions

Feel free to join #sms-irc on irc.freenode.net⁠ and give eta⁠ a hard time about how hard their software is to install.