matrix-bridge-voxtelesys/README.md

# matrix-bridge-voxtelesys

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!

## Installation

    git clone https://source.netsyms.com/Netsyms/matrix-bridge-voxtelesys /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`.

## Configuration

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](https://github.com/nodesource/distributions) (v18 as of commit date)