Categories
Guide/HowTo

Set up Telnyx SMS notifications on Synology DSM 6

Before you proceed, consult the tariff tables and consider setting up rates so you don’t kill your Telnyx balance. This can be done both on Telnyx and on DSM.

Since I first got DiskStation Manager, I’ve been itching to set SMS notifications, not that I strictly needed them or anything but it is nevertheless an awesome feature from the system.

Synology makes amazing products with excellent support but sometimes leaves things very loosely defined and makes some weird choices that take forever to be fixed or improved. Among these there are the federation options/choices and SMS notifications.

For a while I used an Android phone SMS gateway with SIM card to do this but it was a prepaid card and I always kept forgetting to go top up its balance so it could send texts. Where I live, unlimited messages are the norm even on prepaid lines except that the catch is that you have to be topping up the line’s balance every month. It only costs like USD5 to have unlimited messaging for the month. Another option is getting a voice plan that also includes unlimited texting but that costs double of that–the upside from that is that you can be charged automatically to some card or pay over the phone or the carrier’s app, and if you forget about it, it takes a while before your service is cut off. You’re on a contract after all, so you get some leeway.

Telnyx is a great trunking provider with good pricing. It seems to be really big, so big in fact that the number I ported to Telnyx from my previous provider, was actually a Telnyx number already; the old provider was reselling the number.

Setup

Requirements

  • A Synology unit with DSM 6+
  • An SMS-enabled Telnyx phone number
  • Admin access everywhere

Good to have

  • A text editor like TextWrangler, Notepad++, VS Code, TextEdit without formatting (menu Format > Make Plain Text)
  • A terminal window and curl (if it doesn’t have curl and you can’t install it there, you may SSH to another computer that has curl

Create (or edit) a messaging profile

If you already have an associated messaging profile and are not using it just change its API version to API 1 and click on Save. You can leave its name if you wish.

If you haven’t already, on Telnyx Mission Control (their user dashboard) go to Messaging on the sidebar and click on Add new profile.

Set a generic name for it (e.g; Automated) change to API v1 and scroll all the way down to click Save.

Open the profile you just created and scroll down to get the API V1 Profile Secret under Outbound Settings. Paste the code somewhere, no need to save though.

Associate a phone number with messaging profile

In Telnyx Mission Control go to Numbers on the sidebar and locate the number you want to use from the list.

On the Messaging Profile column click the dropdown menu to select the messaging profile you created. Changes here cost money, this is why if your phone number had already a messaging profile associated it’s a better idea to edit it instead so you’re not charged.

Be careful because if it’s got already a profile associated it will not show the dropdown anymore, it will disassociate it straight away, no questions asked. Re-associating it will incur a fee.

On the Telnyx side this is basically it. Login to DSM with any admin account.

Add SMS Service Provider in DSM

In the Control Panel app go to Notifications on the sidebar, click on the SMS tab and finally click on the Add SMS service provider button.

Enter Telnyx on Provider name. Select POST as HTTP Method and on SMS URL enter https://sms.telnyx.com/messages

Click Next to define the headers.

Click Add to define the first header set. These will be changed later so unless specified, copy them as are:

ParameterValue
Content-Typeapplication/json
X-Profile-Secretapi_id

Click Next to define the body sections.

ParameterValue
fromsender
tophone
bodyhello world

Click Next to match values.

Using the dropdowns in the next section, match the values as follows:

Click Apply to return to main window.

In the main window fill the following:

SMS service providerTelnyx
SenderYour phone number in +E.164 format, e.g;
+15554351127
+528459654265
API keyThe API key copied before, e.g;
DGkrru1yvM34KmMnNoid9DL5
Primary phone numberSame as before, in +E.164 compose a number to receive (and test) texting. First box is + sign, second is country code, third is number.

Click Apply and click Send a test SMS message to send a test to the specified number. Adding secondary phone number means you’ll send double the texts for each notification.

Give it some moments, if it arrives, you’re done.

Testing delivery with cURL

Texts are send via REST calls, which are basically requests to a web server like those you do when you use a web browser but instead of delivering something like an image or a page, the code running on the web server interprets the request as an order to do something.

cURL lets you do that minus the browser.

curl -X POST "https://sms.telnyx.com/messages" \
  -H "Content-Type: application/json" \
  -H "X-Profile-Secret: YOUR_MESSAGING_PROFILE_SECRET" \
  -d '{
    "from": "+13125550001",
    "to": "+13129450002",
    "body": "Hello!"
}'

The \symbol is used to break lines so formatting is easier. In reality that command is a single line. Unless wrapped in "" spaces are ignored. But, just so you know… spaces wrapped in "" in this case, are not allowed.

If something is wrong you’ll get some clues in a response. If it goes through you’ll also get a response that it was sent.

Example error
Example success

Note that a successful delivery here means that it was successfully delivered from Telnyx to the carrier of the destination number. It does not mean the carrier has delivered the message to the user.

Other providers

Though the use of REST APIs is very common, the APIs themselves are not standardized. Meaning values such as X-Profile-Secret could be Authorization or Auth-ID in another provider and for every other parameter. They make their own. This is why at the end you must tell DSM which means what so it can replace it, it’s also why you leave some marked as other because while DSM might not need it, your provider does.

I recommend you avoid the big name providers like Twillio. They were smart to let themselves be known when these technologies were catching on and they made partnerships (basically, advertising) with a lot of providers early on but now they’re just marketing. They aren’t easier to set up than any other and have a pretty high price mark up.

Example pricing to the major mobile carriers in Mexico:

TwillioTelnyx
AT&TUSD 0.0490USD 0.0116-0.0169
MovistarUSD 0.0490USD 0.0143
TelcelUSD 0.0490USD 0.0163

While writing this I found even cheaper carriers than Telnyx. For instance, Flowroute at 0.004 vs Twillio at 0.0075 to texts to the US. Both come with a surcharge for some carriers but sadly that’s to be expected from dealing with US-based corporations. Telnyx starts at 0.0059 per message up to 0.0358 for T-Mobile and some other carriers’ numbers in the US, but it has no little to no fine print for their service. They’re upfront and honest about it which, which is increasingly harder to find in a sea of misleading advertising.

Leave a Reply