SMS

SMS sends text messages through a provider and logs every one. Its main use is phone sign-in: a code by SMS the first time, then a 6-digit PIN.

What it is

Two providers exist:

MSG91 sends only registered templates (Indian regulation), so it sends codes and nothing else; there is no free-text SMS.

Turn it on or off

SMS is a switchable feature, id sms, on by default and needing no other feature. To turn it off, list it in src/custom/features.ts:

export const CUSTOM_FEATURES: FeatureChoice = {
    off: ['sms'],
};

With it off:

• the SMS settings tab and the SMS Logs page go, and their URLs show the not-found page; the menu's Email + SMS group is called Email;
• phone sign-in is off whatever User Settings says, and its switch is hidden;
• the functions sendTestSms, checkPhoneSignIn and the phone sign-in functions are not built, so the next full functions deploy deletes them.

Settings and logs stay in Firestore. How the switch works for every feature: Feature ids.

Set it up

1. Open Admin, Settings, SMS.

2. Under Countries, list the countries people can sign in from: type a name, an ISO id or a code (44 or +44) in the search box and pick one. Each shows with its flag, name and code. Only numbers from these countries can sign in by phone, and the list is never empty: the last country has no remove button. A new site has India only.

3. With more than one country, choose the Default country. The sign-in page's country chip starts on it, and numbers typed without a code belong to it. Removing the default makes the first country left the default. With one country there is nothing to choose.

4. Saving stores the countries and their calling codes in Settings/sms; the server reads the codes. It also copies the countries to Settings/users (phoneCountry, phoneCountryCode, phoneCountries), which the sign-in page can read before anyone signs in, while Settings/sms stays admin only. Opening this page puts the copy right if it is missing or out of step. A site saved before countries were stored reads each saved code as its main country (91 India, 44 the United Kingdom, 1 the United States) until it is saved again.

5. To send real messages, choose MSG91 and enter the auth key and the OTP template id. The key is never shown again: leave the field empty to keep the saved one.

6. Click Save SMS settings. Then, under Send a test SMS, pick your country beside the box, enter your own number and click Send test. With MSG91 the test is your OTP template with a made-up code; with the test provider it is only recorded in SMS Logs.

Then turn phone sign-in on under Admin, Settings, User Settings (the SMS page links there). The switch first checks the one Google Cloud setting phone sign-in needs, and shows how to fix it if it is missing (see Google Cloud setup for phone sign-in). With phone sign-in on and the test provider, User Settings also warns that codes are only logged.

Use it

Phone sign-in

1. The person types their mobile number. Numbers in any common shape work (+91 98765-43210, 098765 43210); each is stored as E.164, such as +919876543210.
2. A new number gets a 6-digit code by SMS. After the code, the person enters their name and chooses a 6-digit PIN, and the account is created with the default role from User Settings. New numbers are refused while sign-ups are closed.
3. A registered number signs in with its PIN. After 5 wrong PINs, the PIN is locked and the person resets it with a new code.
4. Forgot PIN? sends a code; after it, the person chooses a new PIN, and every other session of that account is signed out within the hour.

Codes last 10 minutes and allow 5 tries. A number can get a code for the same purpose once a minute and 5 codes an hour; a request inside the minute sends nothing and the page shows the code already sent, and neither it nor an SMS the provider refuses counts towards the 5. A code for another purpose, such as a PIN reset right after a sign-up code, goes at once. Asking again while the code still works sends the same code, with another 10 minutes, so two messages never carry different codes. PINs such as repeated digits or 123456 are refused. A signed-in person can also add a number to their account, or change their PIN, from their profile. Adding a number sends a code; a number verified this way moves from any other account that had it (see Sign-in methods).

SMS Logs

Each message shows the time, the number (To), the message, its type (Sign-in code or Test), its status and the provider. The status is Logged (test provider, stored as logged), Sent (sent) or Failed (failed), with the provider's error after the message. For a real provider the code is replaced by dots in the stored text, so the log never holds a live code. Filter by status to find failures.

Extend it

To send a text from your own Cloud Functions, call sendSms() from functions/src/sms/sendSms.ts. It sends through the configured provider and writes the log:

import { sendSms } from '../sms/sendSms.js';

const code = '482913';
const result = await sendSms({ to: '+919876543210', purpose: 'otp', code, text: `${code} is your code.` });
// result.status: 'logged' | 'sent' | 'failed'

With MSG91 only messages with a code can be sent, and the text is ignored: the OTP template is what arrives. Check isFeatureOn('sms') (from functions/src/feature-flags.ts) first if your app may turn SMS off.

A new provider is a change to core (functions/src/sms/providers.ts), not to an app. Raise it as a feature request.

What it stores

The user record keeps phone and phoneVerified. Nothing is kept in Storage.

All are callables, deployed as arccms-<name>. See Cloud Functions and Data model.

Who can do what

Troubleshooting