You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

153 lines
7.3 KiB

# sms-irc
[![GNU AGPLv3 licensed](](
[![GitHub stars](](
[![IRC chat @ #sms-irc on freenode](](
[![AUR: sms-irc-git](](
A WhatsApp Web and SMS bridge for [internet relay chat (IRC)]( (slightly less beta!)
5 years ago
This repo really lives at [](, but it's also on GitHub as well.
PRs/issues more than welcome!
## What is this?
5 years ago
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
4 years ago
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 \
-e "SMSIRC_CONFIG=/data/config.toml" \
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](
and give [eta]( a hard time about how hard their software is to install.