SMS opt-in — Timely Docs

Every employee in Timely has an sms_opt_in flag. It controls whether any SMS goes to them — shift alerts, publish notifications, time-off responses, the lot.

Why it matters

US carrier rules (TCPA + the major carrier networks) require explicit opt-in for automated messaging. We enforce it at the application layer:

If an employee has sms_opt_in: true and a phone number, they get all enabled SMS for their org.
If sms_opt_in: false (the default for newly-added employees), no SMS goes to them under any circumstances.

There's no separate per-channel toggle — opting out of SMS opts out of all SMS.

Setting opt-in

Three places it can flip:

Per-employee, on the Team page. Click an employee → side panel → SMS toggle. Default for new employees: off.
At signup, when an employee first acknowledges shift alerts via SMS (if your signup flow uses that path).
Via STOP / START keywords — if an employee texts STOP to your Timely number, opt-in flips to false. Texting START flips it back. This is automatic and required by carrier compliance.

STOP keywords

Employees who text any of these to your Timely number will be opted out:

STOP
UNSUBSCRIBE
CANCEL
END
QUIT

They get a confirmation reply: "You've been unsubscribed from Timely." They can text START to re-subscribe.

These keywords are carrier-required and Timely intercepts them before any intent parsing. If you ever need to use the word "cancel" for a feature command (e.g., a shift-swap workflow), it'd need a different keyword to avoid colliding.

When SMS is gated even with opt-in

Opt-in is necessary but not sufficient. SMS only goes out if all of these are true:

The employee is sms_opt_in: true
The employee has a phone number on file
(For shift alerts) the per-week Send SMS Alert toggle is on for that employee's schedule
(For shift alerts) the org has SMS delivery configured

If any one fails, the SMS is silently skipped — no error, no retry, no bill. The skip is logged in the communications log so you can audit "why didn't Sarah get a reminder?"

Per-week shift-alert toggle

Independent from opt-in, each schedule week has a Send SMS Alert toggle. This is in the schedule editor, near the bottom of the Edit Schedule modal.

Default behavior:

For a brand-new week (no schedule yet) — defaults to the employee's sms_opt_in value. So if they're opted in, the toggle is automatically on for new weeks.
For an existing saved week — keeps whatever the manager last set. So a manager who explicitly turned alerts off for a specific week (e.g., a holiday week) won't have it silently flipped back on.

When you toggle an employee's sms_opt_in from false → true, Timely also flips on the per-week toggle for every existing schedule of that employee in one bulk update — so re-enabling SMS opt-in works retroactively without you having to walk through every saved week.

Carrier gateway lookup

When an employee's phone is added to Timely, we look up the carrier and store the gateway domain (e.g., vtext.com for Verizon). This is used as a fallback when direct SMS delivery isn't configured — Timely can send via email-to-SMS instead.

The lookup happens automatically when a phone number is saved. If the lookup fails (rare), the phone still works for the standard SMS path — only the email-to-SMS fallback is unavailable.

Outbound delivery

SMS delivery is handled by Timely — there's nothing to configure on your side. Direct SMS is the default for production accounts; if direct delivery isn't available for a given employee's carrier, Timely automatically falls back to an email-to-SMS gateway using the stored carrier domain. Either way, the experience is the same on your end: hit Publish or wait for the cron, and the message goes out.