# SMS

Let visitors subscribe to SMS on your status dashboard.

Source: https://statusdashboard.com/docs/status-dashboards/subscriptions/sms

> This is a plan-gated feature. If it isn't available in your account, visit the [Billing](/docs/org-mgmt/billing) page or contact support to review your options.

This page covers the public **Subscribe** and manage flows for SMS on your status dashboard. For org-wide subscriber admin and bulk import, see [SMS subscribers](/docs/subscriptions/sms). For message format, delivery logs, STOP/START, and suppression, see [SMS notifications](/docs/notifications/sms).

***

## What visitors see
SMS subscriptions let visitors choose which components to watch and receive **text messages** when matching events are created or updated.

On `/subscribe`, visitors with the SMS channel effectively enabled see an **SMS** tab where they:

1. Select their country and enter a **phone number** (validated with international formatting rules; submitted as E.164).
2. Select one or more **components** from your dashboard (grouped when component groups are enabled).
3. Accept **SMS consent** and **Terms of Service / Privacy Policy** checkboxes.
4. Complete the **reCAPTCHA** check when the dashboard is public (SSO off).
5. Click **Subscribe**.

They must select at least one component and accept both checkboxes to submit. On public dashboards, **Subscribe** stays disabled until reCAPTCHA is completed.

Below the subscribe form, an **Already subscribed?** section lets returning visitors enter their phone number and click **Manage** to receive a text with a link for updating preferences. The manage-request form also requires reCAPTCHA on public dashboards.

## Double opt-in (verification)
SMS subscriptions use **double opt-in**, parallel to [email](/docs/status-dashboards/subscriptions/email#double-opt-in-verification):

1. The visitor submits the subscribe form.
2. StatusDashboard stores a **pending** subscriber record and sends a verification text with a **short link**.
3. The visitor opens the **short link** from the text (`/l/…` on the status dashboard host), which resolves to the verification page (`/subscribe/sms/verify?token=…`).
4. The subscription is **activated** and the visitor is redirected to a management page.

Verification links expire after **24 hours**. If a link expires, the visitor can submit the subscribe form again with the same number (while still unverified).

## Managing preferences
After verification — or after requesting a manage link — visitors land on `/subscribe/sms/manage?token=…`. The management token in the URL (valid for **1 hour**) authorizes read and update operations on that number's subscription. SSO does not replace this token — it only controls whether the visitor may reach the page in the first place.

On the manage page, visitors can:

* See their phone number (read-only).
* Add or remove component selections.
* **Clear all components and save** — they stop receiving notifications but remain subscribed until they change selections again or their manage link expires.
* Return later via **Manage** on the subscribe page to receive a fresh link.

Each new verification or manage-link text **revokes** any previous management link for that subscriber, so only the latest link is valid.

Manage and verify texts use temporary **short links** so messages stay short. Open them on the **live status dashboard hostname** for that page.

Replying **STOP** to any status text opts the number out of future delivery (the subscription record stays in place). See [SMS notifications — STOP and START](/docs/notifications/sms#stop-and-start).

## Subscriber limits
Your plan sets a maximum number of **unique phone numbers** across your **organization** — not per dashboard. **Pending and verified** subscriptions both count when a number is new to your org (first public signup, admin add, or import).

* Each **new** unique number consumes one slot at sign-up time (before verification completes).
* The same number subscribing on a **second** status dashboard does **not** use an additional slot.
* When the org-wide limit is reached, **new** numbers receive an error at submit time. Numbers **already in your organization** may still subscribe on other dashboards.
* The **Subscribe** link remains visible; capacity is enforced when visitors submit the form.

If a visitor never completes verification, the pending record expires after **24 hours** and the quota slot is released automatically. It may take up to an additional **48 hours** for removal to process — during that window a slot may still appear used in the admin quota bar. See [Quota bar](/docs/subscriptions/sms#quota-bar).

Separately, your plan may include a monthly **SMS messages** quota for outbound event and subscription texts. See [SMS notifications](/docs/notifications/sms).

## What admins control vs. what visitors control
| Setting                                 | Controlled by                                                                                              |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Whether SMS subscriptions are offered   | Plan + dashboard **Subscriptions** tab toggle                                                              |
| Which components a visitor watches      | Visitor (at subscribe or on manage page)                                                                   |
| Subscriber capacity                     | Plan quota                                                                                                 |
| Pre-verified admin adds and bulk import | Admin only — see [SMS subscribers](/docs/subscriptions/sms)                                                |
| Admin-verify pending sign-ups           | Admin only — checkmark on **Pending** rows in [SMS subscribers](/docs/subscriptions/sms#verify-subscriber) |

There is **no admin-managed (locked)** option for SMS — that concept applies only to email (for example distribution lists). See [Email subscribers — Admin-managed](/docs/subscriptions/email#admin-managed-locked-subscribers).

## Plan entitlement
A channel is offered on the public dashboard only when:

1. Your organization plan includes **SMS notifications** (`smsEnabled`).
2. You enable **SMS** on that dashboard's **Subscriptions** tab.

Subscriber and message quotas control capacity; they are not the on/off switch for the product capability.

## Security notes
* When SSO is enabled, visitors must authenticate through your IdP before using subscribe or manage APIs — the same gate as the rest of the dashboard. reCAPTCHA is not shown on SSO-protected dashboards.
* On **public** dashboards (SSO off), subscribe and manage-request forms require reCAPTCHA. This applies even when an IP allowlist is configured — allowed IPs must still pass the check.
* Subscription actions are always scoped to a phone number proved via verify or manage tokens; SSO identity alone does not grant access to another person's subscription.
* IP allowlist rules still apply to subscribe traffic when configured.
* Management tokens are opaque, short-lived, and passed in the URL for the active session. Treat manage links like password-reset links — do not share them.
* Short links resolve only when opened on the **correct status dashboard host** for that subscription’s dashboard.