Configuring Twilio for SMS

Twilio is the SMS provider Magentrix uses to send text messages. Once it is connected, the platform can send two-factor authentication codes by SMS, and your Active Classes and triggers can send text messages of their own. You connect Twilio the same way as any other API provider, as a Connected App.

Requirements

To configure Twilio, users must be assigned a security role with the following permissions:

Administrator System Role

You also need a Twilio account, and from it:

Your Account SID
Your Auth Token
An SMS-capable Twilio phone number

All three are available in the Twilio Console. Magentrix does not provision Twilio numbers for you.

To configure Twilio as an API provider:

In the Setup Home page, click Extend > Connected Apps.
Click New.
Select API Provider and then click Next.
Select Basic and then click Next.
Configure the fields:
- Name: Enter a name you will recognize, for example "Twilio".
- Service URL: Enter "https://api.twilio.com"
- Username: Enter your Twilio Account SID.
- Password: Enter your Twilio Auth Token.
- Security Token: Enter your Twilio phone number, in international format, for example +14155552671.
Click Save.

Security Token holds the phone number, not a token. Connected Apps use one set of generic fields for every provider. For Twilio, the Security Token field is read as the default From number on every message. If you leave it empty, messages fail unless the sending code supplies a From number itself.

Name cannot be changed after you save. Active Classes and triggers call the connection by this name, so choose it deliberately. To use a different name later, create a second Connected App and update the code that refers to the old one.

What Each Field Maps To

Magentrix field	Enter	Where Magentrix uses it
Service URL	https://api.twilio.com	The base address of the Twilio API. The platform appends the API version and your account path to it.
Username	Account SID	Identifies your Twilio account, and is the user name in the authorization header.
Password	Auth Token	The password in the authorization header. Stored as a secret value.
Security Token	Your Twilio phone number	Used as the From number whenever the sender is not specified in code.

Using Twilio for Two-Factor Authentication

Connecting Twilio does not switch SMS verification on by itself. To offer SMS as a two-factor method:

In the Setup Home page, go to Security Settings > Two-Factor Authentication.
Turn on Allow SMS Verification.
In SMS Provider, select the Connected App you created.
Click Save.

The SMS Provider list is not filtered. It shows every Connected App on the portal, including ones that have nothing to do with SMS. Confirm you have selected the Twilio record.

Each user needs a mobile number on their profile. The code is sent to the user's Mobile Phone field. Twilio requires international format, so a number stored as a local number will be rejected.

Users receive a message in this form:

Your {Portal Name} verification code: 123456
This code expires in {your Security Code Timeout}
Please do not reply to this message.

For the rest of the two-factor settings, see Enabling and Configuring Two-Factor Authentication.

Sending SMS From Your Own Code

Once the Connected App exists, Active Classes and triggers can send messages through it by referring to it by name. The developer reference, including the available methods and the response you get back, is in Messaging.Twilio in the Developer Guide.

If your code does not specify a sender, the Security Token value is used as the From number.

Troubleshooting

Symptom	Cause and resolution
Twilio returns A 'From' phone number is required (error 21603).	The Security Token field is empty and the sending code did not supply a From number. Edit the Connected App and enter your Twilio phone number.
Users get their two-factor code by email instead of SMS.	This is the built-in fallback. When Twilio rejects a message, the platform logs a warning and emails the code so the user is not locked out. Check the warning for the reason Twilio gave.
Authentication fails against Twilio.	The Username must be the Account SID and the Password must be the Auth Token. Re-enter the Auth Token if you are unsure it is correct, and confirm it has not been rotated in the Twilio Console.
Messages fail for some users only.	Their Mobile Phone value is missing, or is not in international format. Numbers are passed to Twilio exactly as stored.
SMS is not offered as a verification method.	Allow SMS Verification is off, or no SMS Provider has been selected in the two-factor settings.
Nothing sends after renaming the connection.	The Name cannot be edited after saving, so a new Connected App was created. Update any Active Class or trigger that referred to the old name.

Table of Contents