I will discuss the main use case for this program in a blog post that I haven't written yet.
This program implements a server that accepts webhook connections from Telnyx to receive SMS messages and calls. In the latter case, it also acts as an answering machine by playing a recorded message and recording the call into an mp3 file. Notifications are sent to the recipient using either Pushbullet or a Telegram bot (or both).
Support for receiving SMS via Twilio was added later, making the name something of a misnomer.
The program is written in Crystal using the Kemal framework. The server is self-contained (it doesn't need another server like Apache or nginx) and can (and should) be run with normal user credentials.
This program needs to run on a computer with a public IP, because Telnyx will access the webhooks via standard URL endpoints, so most likely you'll be running it on a VPS (you can get one cheaply from a company like Virmach).
If you don't have Crystal yet, you need to first install it. After that, installation is simple:
git clone https://github.com/larilampen/telnyx-nomad.gitcd telnyx-nomad && shards installcp config.json.template config.json- Edit
config.jsonwith your details, as described below.
Look at the provided template (if you followed the above steps, config.json now contains a copy of it) to see the structure of the configuration file. There are three types of items in it.
Notifications: You can specify credentials for Pushbullet or Telegram. If both are defined, notifications will be sent to both. If neither is defined, no notifications will be sent, but the program will still log events and answer calls.
For Pushbullet, the API token (unique to each user account) is needed, along with a device ID (which specifies which of your devices the notifications will be sent to).
For Telegram, first create a bot following the official instructions. You will receive an access token for the bot. Additionally, a chat ID needs to be specified to ensure messages are sent to you only, and not to anyone who happens to chat to the bot.
Credentials: For Telnyx, an API key is required.
Numbers: A list of the phone numbers you use at Telnyx. Each has a name (used instead of the number simply to keep the notifications shorter and easier to read) and a message URL, which is the message that will be played when a call is received.
Other options: The field default-message specifies what message will be played in case a number is called that isn't included in the numbers section. The field port specifies the port number to listen to.
The best format for the answer message files is a monaural mp3 with a relatively low bitrate, because phone lines don't support stereo, nor are they exactly high fidelity in terms of sound quality.
You can choose to host the message files on another server, or they can be placed in the folder public (create it if it doesn't exist), which will cause Kemal to automatically serve them when requested.
Simply run with crystal src/telnyx.cr, or build into a binary (crystal build src/telnyx.cr) if desired. Running inside tmux or screen makes it easy to detach and rejoin the session when needed.
- Fork it (https://github.com/larilampen/telnyx-nomad/fork)
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create a new Pull Request