Skip to main content
This page is part of Example app: a full OneSignal integration, which follows one real app from end to end. The app is Clean Beans, a cleaning rota for shared homes, built with Expo (React Native) and a Supabase backend. Clean Beans uses SMS for two jobs that push and email cannot do well: proving that a phone number belongs to the person who typed it, and reaching someone who does not have the app yet. Both are sent to a raw contact, a phone number or email address, not to an External ID. That is the main difference from every other send in this guide.

Verify a phone number with a one-time code

In User Profile, a user can add a mobile number. The app asks the backend to text a 6-digit code, the user types it in, and the backend checks it. Only then does the number count as verified.
The phone number card in three states: entering a number, entering a code, and verified

Adding a phone number: enter the number, enter the code, verified.

OneSignal delivers the text message. It does not create or check the code. Everything else is your backend’s job.
1

Generate a code and store it hashed

The code comes from a cryptographic random source. Only a keyed hash is stored, bound to the user and the phone number, so the table alone cannot be turned back into codes. The key is a dedicated secret, OTP_HASH_SECRET, used for nothing else. Both functions refuse to run if it is not set.
supabase/functions/_shared/otp.ts
supabase/functions/send-otp/index.ts
2

Send it by SMS through OneSignal

include_phone_numbers targets the number directly. If OneSignal has never seen it, it creates an SMS subscription for it.
supabase/functions/send-otp/index.ts
3

Check the code

The backend hashes what the user typed and compares it with the stored hash. A wrong guess is counted. After five, the code is dead and a new one must be requested.
supabase/functions/verify-otp/index.ts
4

Register the number as an SMS subscription

Once the backend confirms the code, the app adds the number to the signed-in user.
src/lib/phone.ts
The app repeats this after every sign-in, so a verified number follows the user to a new device.
src/lib/phone.ts
Call addSms() after login(), as with email. A send to a raw phone number creates a subscription that belongs to no one. addSms() from a signed-in app attaches that subscription to the user. Until then, it appears in the dashboard as a separate user record.

Protect the endpoint

A function that sends a text message on request costs money each time it runs, and it is a target for abuse. Clean Beans applies these limits.
supabase/functions/send-otp/index.ts
The verified number is kept in its own table. Only the backend can write to it, so the app cannot mark a number as verified, and other members of a household cannot read it.
supabase/migrations/028_phone_verification_and_invites.sql
A phone number on its own is not permission to text it. For verification codes, a disclosure next to the phone field is enough, and it must say who is sending, what they will send, that rates may apply, and how to stop.
src/components/PhoneVerificationCard.tsx

Invite someone who is not a user yet

On the Household screen, a member can invite someone by text or by email. The invitee has no account, no device registered, and no External ID. The backend sends to the raw contact, with a link that opens the app’s join screen.
The invite dialog and the invitation text message it sends

Inviting a housemate by text or email, and the message they receive.

The same endpoint handles both channels. SMS uses include_phone_numbers. Email uses email_to, with the subject and HTML body passed inline.
supabase/functions/send-invite/index.ts
The link is a Universal Link, set up in Open the app from ordinary web links. Two details keep it working:
  • Email click tracking is turned off. Tracking rewrites links to pass through a tracking domain, and a rewritten link no longer opens the app.
  • The SMS does not use a tracked short link, for the same reason.
When the invitee installs the app and signs in, the app’s login() and addEmail() or addSms() calls attach the subscription that the invitation created to their new user.
The invitee has not agreed to hear from your app. Rules for unsolicited texts and emails vary by country and can be strict. Clean Beans includes this flow to show how sending to a raw contact works, and limits each member to ten invitations a day. Before using the pattern in production, check the rules for the places you send to, and consider having the inviter send the message from their own phone.

Things to know

  • A sender is required. Choose a default sender in Settings > SMS, or pass sms_from with each request. With neither, the request is rejected with “A valid number is required for ‘From’ field”.
  • A 200 response does not always mean a message was sent. Check for a message id in the response, not only the status code.
  • Store numbers in E.164 format, a plus sign followed by the country code and number, and reject anything else before calling the API.
  • OneSignal Verify is the managed alternative. It generates and checks codes for you. Clean Beans builds its own to show the whole flow.
Dashboard setup. Complete SMS setup and choose a default sender that can reach the countries your users are in.

One-time passwords

OneSignal Verify and building your own.

SMS opt-in and collection

Consent and disclosure requirements.

SMS API reference

Every SMS parameter.