Single-user Matrix.org Application Service (AS) to bridge SMSes to the Matrix network!
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
migrations The Great Refactor (part I): make SMS handling actually manageable May 24, 2018
src those changes were a mistake May 27, 2018
.gitignore SMS -> Matrix works! Feb 16, 2018
Cargo.lock
Cargo.toml The Great Refactor (part I): make SMS handling actually manageable May 24, 2018
LICENSE this stuff is GPLv3 Feb 16, 2018
README.md clarify quasi-deprecation Jun 28, 2018
Rocket.example.toml documentation on how to get this thing working Feb 17, 2018
sms-registration.yaml documentation on how to get this thing working Feb 17, 2018

README.md

matrix-appservice-sms

What is this?

This is a Matrix.org Application Service (AS) that bridges SMS messages to Matrix, using a USB 3G modem plugged into a server. Crucially, it only works for one user - obviously, if you only have one 3G modem, it doesn't really make sense to support more than one user...

What do I need to run it?

  • an instance of PostgreSQL
  • a Huawei USB 3G modem, like the Huawei E3531, or Huawei E169
    • Other models of 3G modem are available. Essentially, if it uses the AT/Hayes command set, and implements a bunch of common commands, it'll probably work.
    • This has been tested working with the Huawei E3531, though.
  • a nightly version of Rust; see below for details
  • a decent amount of patience ;p

You may also be interested in sms-irc, which is in many ways the successor to this project. This project isn't that maintained at the moment, with work mainly being focused on sms-irc, but PRs and issues are still very much welcome and will receive attention!

How do I set this up?

Oh, man.

Set up the 3G modem

  • Firstly, ensure that your 3G modem presents itself as a serial port - usually with a path like /dev/ttyUSBX.
    • Advice is available on the Arch Wiki, and varies from model to model. You might need to do a bit of googling to figure out how to poke your modem into appearing as a serial device, as many appear as mass storage devices with software by default.
    • For the Huawei E3531, try sudo usb_modeswitch -v 12d1 -p 15cd -M '55534243123456780000000000000011062000000100000000000000000000'.
      • If that doesn't work, try changing the 12d1 and 15cd above with whatever VID:PID combo appears next to the device in lsusb.
      • For example, if your device presents itself as a ID 12d1:1506 Huawei Technologies Co., Ltd. Modem/Networkcard when lsusb is run, you'd use -v 12d1 and -p 1506.
      • Again, this stuff is really dependent on your modem. Google is your friend, if the above device didn't work for you!
    • Some modems (like the E3531) present three serial ports: /dev/ttyUSB0-2. You want /dev/ttyUSB2 in this case.
    • Once you've found the device path for your modem, try connecting to it with sudo minicom -D /dev/ttyUSB2 (replacing /dev/ttyUSB2 with the path for your modem if different), and typing AT<Enter>. If you get OK back, you've found the right path!
  • Also ensure that the user you're going to run the AS as can read and write to this serial port. (sudo chmod 777 /dev/ttyUSB2 does the job, but is pretty bad security-wise; it's better to configure users and groups correctly.)

Set up Rust

  • You need the latest nightly version of Rust installed; check out their install page. If you install with rustup, change the default configuration when prompted to install the nightly toolchain.
    • NB: As of 2018-05-24, this project only works with rustc 1.27.0-nightly (e5f80f2a4 2018-05-09) - override your toolchain to use that nightly!
    • This can be done with $ rustup override set nightly-2018-05-10.
  • Build the project with cargo build.
  • Then, install diesel_cli with cargo install diesel_cli.

Set up the database

  • Run DATABASE_URL=[url] diesel migration run, substituting [url] for your database URL (e.g. postgresql://localhost/database).

Set up synapse

  • Replace the placeholders in sms-registration.yaml with sane values (for the tokens and id, generate some random crap, but make sure all of the values are different; for the URL, put the URL of where you're going to put your matrix-appservice-sms instance).
  • Copy this somewhere (usually /etc/synapse) readable by synapse.
  • Edit app_service_config_files in your synapse homeserver.yaml, and add the path to your sms-registration.yaml file. e.g.:
app_service_config_files: ["/etc/synapse/sms-registration.yaml"]
  • (Hold off on restarting synapse for now; we want to make sure that the AS is reachable first.)

Set up the AS

  • Replace the placeholders in Rocket.example.toml, following the guidance therein, and rename it to Rocket.toml.
  • Run the AS with cargo run.
  • Now, restart synapse.

Use the AS

  • Invite @_sms_bot:[your HS] to a 1-1 chat.
  • Issue !sms [phone number] in that chatroom to start texting! (You'll get invited to a private chat with that phone number.) Make sure the number is in international format (e.g. +440123456789) for best results.

Your setup instructions are crap! / It didn't work!

License

  • This is GPLv3-licensed software.