Node.js script/daemon to (hackily) send SMS from the Voxtelesys API to Matrix and back.
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Skylar Ittner 48eb005977 Clean up some unneeded logging 1 month ago
nbproject Fix some bugs, make Matrix SDK a little newer 8 months ago
.gitignore Add \!sms command to send to a new number 3 years ago Add and license metadata 4 years ago Update readme 7 months ago
config.example.json Get access token if unset in config.json 7 months ago
main.js Clean up some unneeded logging 1 month ago
matrix-bridge-voxtelesys.service Improve unit file and instructions 4 years ago
package-lock.json (`npm i` required!) Fix a bug where SMSes won't send to "old" chats 1 month ago
package.json (`npm i` required!) Fix a bug where SMSes won't send to "old" chats 1 month ago


When someone texts your Voxtelesys DID, this script creates a Matrix room named with the sender's number, posts their SMS in it, and invites you (the users in config.json) to the room. When someone posts a message in the room this script sends it as an SMS to the original sender. Back and forth it goes!


git clone /opt/matrix-bridge-voxtelesys
cd /opt/matrix-bridge-voxtelesys
cp config.example.json config.json
nano config.json
npm install
adduser --system --no-create-home matrix-bridge-voxtelesys
cp matrix-bridge-voxtelesys.service /etc/systemd/system
systemctl enable matrix-bridge-voxtelesys
systemctl start matrix-bridge-voxtelesys

Or just run node main.js.


Here's what the various config options mean.

  • homeserver: Matrix homeserver.
  • mediaurlpath: The public HTTP url for accessing media sent by a Matrix user. The parts in curly brackets will be replaced with the proper values. Check what to set the domain to by right-clicking a media file in Element.
  • matrixdomain: The part after the @ in your username.
  • matrixuser: Bot account username for this bridge.
  • matrixpass: Bot account password.
  • matrixaccesstoken: Bot account access token. If empty, one will be fetched and written to the config for you.
  • inviteusers: List of users that the bot will invite to new SMS rooms.
  • smsapikey: Voxtelesys SMS API key.
  • smsfrom: Default DID. Outgoing SMS will be sent from this number.
  • smsonlyto: List of DIDs this bridge should handle incoming SMS from.
  • listenport: HTTP port for webhook endpoint server.
  • publicurl: Public URL of this bridge's built-in HTTP server.
  • loglevel: debug, info, or error.
  • smsinterval: Bridge will poll Voxtelesys API every X seconds. Set to 0 to use webhook only.

Webhook Setup

In the Voxtelesys Portal, go to APIs -> Messaging Applications. Edit your application and set HTTP Method to "POST", Events to "Inbound messages (MOs)", MO Webhook to "http://bridge-url:8069/webhook", and Authentication to "None".

Starting a new conversation

When a SMS is received from a new number, a new room is created. If you need to send a message to a new number, simply type something like !sms 14065551234 into an existing SMS room. You'll be invited to join a new room and will then be able to send your message.

Chat Commands

Chat commands can be issued in any room the bot is joined to.

  • !sms 1234567890: Create a new empty SMS room for the provided phone number, and invite all invitusers to the room. Texts will send from the smsfrom number.
  • !sms 1234567890 9876543210: Create a new empty SMS room, and invite all invitusers to the room, as above. Texts will send from the second number entered.
  • !fixusers: Goes through all the SMS rooms, checking membership against inviteusers. If anyone's missing from a room, they're invited back.

Known Issues/Limitations

  • Any messages posted in a Matrix room while the bot is offline will not be relayed to SMS when it comes back.
  • Only unread SMS are fetched, so if anything else is checking the API this bot won't get those.
  • If it crashes try the latest Node.js LTS (v18 as of commit date)