Skip to main content

Telnyx SMS

The telnyx plugin sends text messages to your users through your own Telnyx account and sender number. It sends phone number verification codes, codes for sensitive actions such as withdrawals and password resets, and a message when a deposit or withdrawal completes.

What you need​

  • The Enterprise plan on HollaEx Cloud.
  • A Telnyx account. Telnyx bills you directly for the messages you send.
  • A Telnyx phone number with messaging turned on, to send from.
  • No other SMS plugin installed. Only one can run at a time (see Compare the SMS plugins).

Set it up​

  1. Get your Telnyx details. In the Telnyx Mission Control Portal:

    • create a V2 API key under Auth → API Keys;
    • under Numbers → My Numbers, pick a number with messaging enabled and note it in international (E.164) format, for example +15555550123.

  2. Install the plugin. Go to Operator Controls → Exchange → Plugins, find telnyx under Available to install and click Install.

  3. Configure it. Click Configure on the plugin, fill in the settings below and save.

    SettingWhat it does
    apiKeySecret, required. Your Telnyx V2 API key.
    fromNumberRequired. The number messages are sent from, in E.164 format such as +15555550123. The plugin won't start if the number isn't in this format.
    send_sms_depositSend an SMS when a deposit completes. Default: on.
    send_sms_withdrawalSend an SMS when a withdrawal completes. Default: on.
    send_sms_user_verificationSend codes for actions such as withdrawals and password resets by SMS to users who chose SMS for their codes. Default: on.

  4. Test it. Sign in to your exchange as a test user, add a phone number and confirm it. Then make a small deposit and check that the SMS arrives.

What your users see​

  • Phone verification. A user adds their phone number on the exchange and gets an SMS with a code. The code is valid for 6 minutes. To add a number they also enter a confirmation code from their email, and their 2FA code if 2FA is on.
  • Action codes. Users who chose SMS for their verification codes get them by text, for example when they withdraw or reset their password.
  • Deposit and withdrawal messages, such as "Your USDT deposit for amount 15.9987 is confirmed".

The message text is fixed. You can't change it from the settings. If you need your own wording, use the AWS SNS plugin.

Phone numbers are protected like a login​

A verified phone number receives the codes for sensitive actions, such as withdrawals and password resets. Whoever controls the number can approve those actions. So the plugin treats a phone number like a login credential:

  • Adding a number needs extra proof. To add a phone number, the user enters the code from the SMS, a confirmation code sent to their account email and, if they have 2FA turned on, their 2FA code. Afterwards the account's email address, if it has one, gets a message that a number was added, with most digits hidden.
  • Users can't replace their number. Once a number is on an account, the user can verify that same number again but can't swap it for a different one. No SMS goes to the new number. They see "Your phone number can't be changed here. Please contact support."
  • One number, one account. A number already verified on another account is refused. The user sees "This phone number is already in use on another account."
  • Deposit and withdrawal SMS go only to verified numbers. A number that was typed in but never verified gets no notifications.

What this means for you: a user who lost their phone or changed their number has to come to your support. Confirm who they are before you change anything, then edit the number from their profile in Operator Controls (Edit User Data). See Users & Review Queue.

How it works​

  • The plugin checks for another SMS plugin when it starts. If one is already installed, it doesn't start and emails your exchange's audit address that the second SMS plugin was blocked.
  • If the API key or sender number is missing, the plugin doesn't start and nothing is sent.
  • A user who requests too many codes, or enters too many wrong ones, is blocked from SMS verification for 24 hours. They see "Too many requests. Your account is blocked for 24 hours".

Compare the SMS plugins​

All four SMS plugins send the same three kinds of message, and each one can be turned off in the settings:

  • Deposit SMS (send_sms_deposit): sent when a deposit completes.
  • Withdrawal SMS (send_sms_withdrawal): sent when a withdrawal completes.
  • Verification SMS (send_sms_user_verification): codes for sensitive actions, such as withdrawals and password resets, for users who chose SMS for their codes. Phone number verification codes are always sent.

They differ in the provider and in a few details:

PluginProvider account you needEdit the message textPhone number treated as a login credential
SMS via AWS SNS (sms)AWS, with SNSYesYes
Telnyx (telnyx)Telnyx, with a messaging-enabled numberNoYes
Messente (messente-sms)Messente, with API accessNoYes
Sinch (sinch)Sinch, with an SMS service planNoNo

You can install only one SMS plugin at a time. To switch, remove the one you have, then install the new one.

Troubleshooting​

  • No SMS arrives. Check the API key, and that the sender number is in E.164 format and has messaging enabled in Telnyx. Check that no other SMS plugin is installed. Then check the plugin logs.
  • Deposit or withdrawal SMS don't arrive, but verification codes do. The user's phone number isn't verified, or the setting for that message is off.
  • "Adding a phone number is not supported on this exchange." Your exchange can't issue the email confirmation code that adding a number needs, so no number is saved. Open a ticket.
  • "Confirm adding this number with the code sent to your email." or "Enter your 2FA code to add this phone number." The user left out the email confirmation code or the 2FA code.

Need help? Open a ticket from your HollaEx dashboard.