SMS for Boom Media

01The ruling — SMS is not a 15th app

Checked against SaaS/.md/APP_BOUNDARIES.md and the one-app-per-job rule.

"Add SMS" sounds like one feature. It's actually three different jobs, and conflating them is exactly what creates the overlap your boundaries doc exists to prevent:

Why Replyee owns the conversation

This follows the exact shape of ruling #10 (website translation → Rankee): a capability every app wants, assigned to the one app whose job it already is, with fences around the rest.

• It already is an inbox. Boundaries doc: Replyee owns "bots, agent inbox, human takeover, visitors, leads, canned replies." An SMS thread is a chat thread with a different transport. Building a second inbox elsewhere is the definition of the overlap you banned.
• The RAG engine is the differentiator. Replyee can already answer questions from a knowledge base. Point that at SMS and you sell "your texts answer themselves at 9pm" — not "a blast tool." Nobody else in the suite can do that.
• The SalesIQ upgrade plan is already building channels. Replyee/.md/SALESIQ_UPGRADE_PLAN.md is heading toward multi-channel. SMS is the natural second channel; the inbox, agent presence, and canned replies are sunk cost.
• The buyer's motive test. "I want to text my customers and have them text back" = a conversation product = Replyee's job. (Same test that gave translation to Rankee: the motive was search reach.)

The fence — who sends what

Every app below sends through the one rail. None of them gets its own inbox, its own Twilio integration, or its own consent list.

02How it works — the shared send rail

One rail, one consent ledger, one inbox, many senders. Every app in the suite (and B.O.O.) sends through the same @boom/sms service — nobody imports Twilio directly, nobody keeps their own consent list.

Campaigns split by purpose — not a new "blast app"

The rail is shared plumbing; the campaigns are owned by whichever app already owns that job. That's how "add SMS" stays inside the one-app-per-job rule instead of spawning a 15th app.

Message paths, traced

Shared schema (new tables in shared Supabase, prefix sms_)

-- One consent record per (client, phone). THE compliance backbone.
create table sms_consent (
  id            uuid primary key default gen_random_uuid(),
  client_id     uuid not null,              -- the business (tenant)
  phone         text not null,              -- E.164 only: +15617828290
  status        text not null default 'pending', -- pending|opted_in|opted_out
  -- Proof of consent. If you can't produce this, you have no defense.
  source        text not null,              -- web_form|checkout|keyword|import|verbal
  source_detail jsonb,                         -- {url, ip, user_agent, form_snapshot_id}
  consent_text  text not null,              -- EXACT wording shown at opt-in
  opted_in_at   timestamptz,
  opted_out_at  timestamptz,
  unique (client_id, phone)
);
create index on sms_consent (phone) where status = 'opted_out';

-- Every message in/out. Audit trail + billing source of truth.
create table sms_messages (
  id            uuid primary key default gen_random_uuid(),
  client_id     uuid not null,
  thread_id     uuid,                          -- FK → Replyee thread
  direction     text not null,              -- outbound|inbound
  app           text not null,              -- localey|rewardee|dashee|replyee|boo…
  phone         text not null,
  body          text not null,
  segments      int  not null default 1,     -- what you actually bill on
  encoding      text,                          -- gsm7|ucs2  ← see the emoji trap, §4
  twilio_sid    text unique,
  status        text,                          -- queued|sent|delivered|undelivered|failed
  error_code    int,                           -- 30007 = carrier filtered (spam flag)
  cost_usd      numeric(10,5),
  created_at    timestamptz default now()
);

-- Per-client Twilio wiring (one Messaging Service per client, §3)
create table sms_clients (
  client_id            uuid primary key,
  twilio_subaccount_sid text,
  messaging_service_sid text,
  phone_number          text,
  brand_sid             text,   -- TCR brand
  campaign_sid          text,   -- TCR campaign
  registration_status   text,   default 'unregistered',
  monthly_included      int,    -- plan allowance
  business_hours        jsonb   -- quiet-hours enforcement, §4
);

The rail — one function every app calls

// packages/sms/src/send.ts  —  the ONLY place Twilio is imported.
import twilio from 'twilio'

export async function sendSms({ clientId, phone, body, app, kind }: SendArgs) {
  // 1. E.164 or reject. No exceptions — bad formats fail silently at carriers.
  const to = toE164(phone)
  if (!to) throw new SmsError('INVALID_PHONE', phone)

  // 2. CONSENT GATE — the whole reason this is centralized.
  //    Transactional msgs tied to a user action may bypass marketing consent,
  //    but NEVER bypass an explicit opt_out. STOP means stop. Always.
  const consent = await getConsent(clientId, to)
  if (consent?.status === 'opted_out') throw new SmsError('OPTED_OUT', to)
  if (kind === 'marketing' && consent?.status !== 'opted_in')
    throw new SmsError('NO_MARKETING_CONSENT', to)

  // 3. Quiet hours — TCPA: no marketing before 8am / after 9pm LOCAL to the recipient.
  if (kind === 'marketing' && isQuietHours(to)) return queueForMorning(...)

  // 4. Append opt-out language to marketing. Carriers check for this.
  const text = kind === 'marketing' ? `${body}\n\nReply STOP to opt out.` : body

  // 5. Count segments BEFORE sending — this is your cost + the emoji trap (§4).
  const { segments, encoding } = countSegments(text)
  if (encoding === 'ucs2') warn('UCS-2: 70 chars/segment — 2.3x cost', { app, text })

  // 6. Send via the CLIENT'S messaging service (not a raw number) — §3.
  const { messaging_service_sid, twilio_subaccount_sid } = await getClient(clientId)
  const client = twilio(process.env.TWILIO_API_KEY_SID,      // SK… key, NOT the auth token
                        process.env.TWILIO_API_KEY_SECRET,
                        { accountSid: twilio_subaccount_sid })

  const msg = await client.messages.create({
    to, body: text,
    messagingServiceSid: messaging_service_sid,
    statusCallback: `${process.env.SMS_WEBHOOK_BASE}/api/sms/status`,
  })

  await logMessage({ clientId, app, phone: to, body: text, segments, encoding,
                    twilio_sid: msg.sid, direction: 'outbound' })
  return msg.sid
}

Inbound webhook — STOP handling is non-negotiable

// apps/replyee/app/api/sms/inbound/route.ts
export async function POST(req: Request) {
  // ALWAYS validate the signature. Without this, anyone can forge an opt-in
  // or inject messages into a client's inbox.
  if (!validateTwilioSignature(req)) return new Response('forbidden', { status: 403 })

  const { From, Body, To } = await parseForm(req)
  const clientId = await clientIdForNumber(To)
  const word = Body.trim().toUpperCase()

  // Twilio auto-handles STOP/HELP by default, but you MUST mirror it into your
  // own ledger — otherwise your apps keep queueing sends Twilio silently drops,
  // and your "delivered" numbers lie to you.
  if (['STOP','STOPALL','UNSUBSCRIBE','CANCEL','END','QUIT'].includes(word)) {
    await setConsent(clientId, From, 'opted_out')   // suppresses ALL apps, instantly
    return twiml()  // empty — Twilio sends the confirmation itself
  }
  if (['START','YES','UNSTOP'].includes(word)) {
    await setConsent(clientId, From, 'opted_in', { source: 'keyword', consent_text: word })
    return twiml()
  }

  // Real message → Replyee thread. AI drafts; human can take over.
  const thread = await upsertThread({ clientId, channel: 'sms', contact: From })
  await appendInbound(thread.id, Body)
  await notifyAgents(thread.id)

  if (await aiAutoReplyEnabled(clientId)) {
    const answer = await ragAnswer(clientId, Body)   // ← existing Replyee engine
    if (answer.confidence > 0.7) return twiml(answer.text)
  }
  return twiml()  // silence → a human answers in the inbox
}

2·5How it reaches the client's dashboard — the Next.js request path

The most common question: "is SMS an API through the SaaS app?" Yes — every text in and out goes through an API route inside the SaaS app. There is no direct browser-to-Twilio call and no separate SMS server. The dashboard is just React pages in the same Next.js app talking to its own API routes.

The request path, traced both ways

Outbound — staff clicks Send in the dashboard:

Inbound — customer replies:

The three layers

The API route the dashboard calls — make "it's an API" concrete

// app/api/sms/send/route.ts — a Next.js Route Handler. Runs ONLY on the server.
// This is the "API through the SaaS app": the dashboard POSTs here, never to Twilio.
import { sendSms } from '@boom/sms'

export async function POST(req: Request) {
  const session = await getSession(req)          // Supabase auth — who is logged in?
  if (!session) return unauthorized()
  const clientId = session.client_id            // tenant scope from the SESSION, not the body

  const { phone, body, app } = await req.json()
  const sid = await sendSms({ clientId, phone, body, app, kind: 'transactional' })

  return Response.json({ ok: true, sid })      // the browser only ever sees this JSON
}

// dashboard component (client) — no Twilio, no secrets, just a call to your own API.
await fetch('/api/sms/send', {
  method: 'POST',
  body: JSON.stringify({ phone, body }),   // client_id is NOT sent — the server derives it
})

Where the client actually sees it — standalone or embedded

Per the suite's model, apps are embedded into the client's own website, not sold as standalone logins. SMS follows the same two shapes:

Next up — two dashboards to light up: Big Mike's Bail Bonds & Fern House

Both ride the exact path above: their dashboard (Dashee) → the app's /api/sms/* routes → @boom/sms → their own number under their own 10DLC brand, all sharing the one consent ledger.

03The 10DLC reality — read this before anything else

This is not a technical problem. It's a registration problem, and it's the thing that will actually slow you down.

You are an ISV, not a direct customer

Because you send on behalf of your clients' businesses, Twilio classifies you as an ISV / reseller. That changes the model:

• Set your primary Business Profile identity to "ISV Reseller or Partner."
• For each client, create a Secondary Customer Profile via the TrustHub API → then a Brand → then a Campaign → attach a Messaging Service → attach their number.
• Twilio's recommended architecture (Type #1) is one subaccount per client. This matters: if one client sends non-compliant traffic in a shared account, Twilio may suspend the primary account — taking down messaging for every other client at once.

What each client must give you (the real onboarding cost)

The $4.50 fee is trivial. This list is the actual friction — it's a form your client has to fill out, and it's why self-serve onboarding (Phase 4) matters:

Approval typically takes 1–3 business days (sometimes longer with vetting). Plan for it in your client onboarding sequence — don't sell "live today."

Local long code vs toll-free — pick per client

Recommendation: local 10DLC as the default — a West Palm customer answers a 561 number and ignores an 800 number, and that conversion difference dwarfs the ~$5/mo delta. Keep toll-free in your pocket for rejected brands and any high-volume client.

Do you buy a number for each client, or do they share yours?

04What it actually costs

Twilio list pricing, verified 2026-07-17. Carrier fees are pass-through and are the line everyone forgets.

Worked examples (what a real client costs you)

Usage @ $0.015/segment all-in, assuming 1 segment/message. Fixed = number + campaign fee. Inbound replies count — a two-way client's real volume runs ~30% above outbound-only, which is why the heavy tier's margin is the one to watch.

05Sample messages

Every template stays under 160 GSM-7 chars where possible. Marketing needs opt-out language; transactional doesn't.

The opt-in form — you need this before you can register

TCR requires proof of opt-in. This exact form (screenshot + live URL) is what you submit. It's also what saves you in a TCPA dispute, so log the snapshot.

<!-- Required elements. Every one of these is load-bearing. -->
<label>
  <input type="checkbox" name="sms_consent">   ← UNCHECKED by default. Pre-checked = invalid consent.
  I agree to receive text messages from Big Mike's at the number provided.
  Msg & data rates may apply. Msg frequency varies.
  Reply STOP to cancel, HELP for help.
  <a href="/privacy">Privacy Policy</a> · <a href="/terms">Terms</a>
</label>

• Never pre-check the box. Pre-checked consent is not consent.
• Consent can't be a condition of purchase — the checkout must work with the box unticked.
• Store the exact wording shown in sms_consent.consent_text — if you change the form later, old records must keep the old text. That's why it's a column, not a config lookup.
• No buying lists. No importing a CRM dump as opted-in. Prior business relationship ≠ SMS consent. This is the fastest way to get a brand banned and a client sued.

06What to charge

Matches your existing $29/$59/$99 ladder. Sold as a Replyee add-on, not a separate product.

Why these numbers

• Overage at 2–3x cost ($0.03–0.05 vs $0.015) is normal and defensible; it also self-corrects the emoji problem — heavy users upgrade rather than bleed you.
• AI auto-reply gated at Growth is the upgrade lever. Starter is deliberately a little painful: it's a two-way inbox someone has to staff. Growth is "it answers itself."
• Undercuts the category badly. Podium runs ~$399/mo for essentially this. SimpleTexting ~$39/500. At $59 with AI auto-reply included you're the value play, and you're bundling into a suite they already pay you for.
• Don't sell SMS standalone. Sell it as the add-on that makes Replyee/Localey/Rewardee better. Standalone SMS invites a Podium comparison; bundled, there's nothing to compare it to.

6·5Billing, metering & ROI — who tracks what

"How do I bill them, track ROI, and which SaaS is tracking all of this?" — three different jobs, three owners, zero overlap. The tiers in §06 are the prices; this section is who meters, charges, and reports them.

1 · The meter — sms_messages is the single source of truth

Every message already logs everything billing needs (§02 schema): segments, encoding, cost_usd, status, app, client_id. You bill off this table — never off Twilio's console or memory. You control it, it's per-client and per-app, and you can show it to the client in a dispute. A monthly rollup is one query:

-- Usage per client for the current billing period → drives Stripe + Dashee.
select client_id,
       count(*)          as messages,
       sum(segments)     as segments,       -- what you actually bill on
       sum(cost_usd)     as twilio_cost,    -- what Twilio charged YOU
       count(*) filter (where status = 'delivered') as delivered,
       count(*) filter (where direction = 'inbound')  as replies
from sms_messages
where created_at >= date_trunc('month', now())
group by client_id;

2 · The biller — Replyee owns the Stripe side

SMS is sold as a Replyee add-on (§06), so the money lives in Replyee — which already has Stripe wired. Keeping it in one place is deliberate: if Localey, Rewardee, and Dashee each billed their own SMS, a client with three of them would be charged three times for one rail.

• Base plan = a Stripe subscription — recurring $29 / $59 / $99 with an included allowance (250 / 1,000 / 2,500).
• Overage = a Stripe metered price. Each period, take segments − allowance from the rollup and report it to Stripe as a usage record; Stripe adds it to the invoice at your overage rate ($0.03–0.05).
• Setup = a one-time Stripe invoice item ($25) at onboarding, covering the ~$19.50 TCR pass-through.
• The allowance counter reads the meter, not Stripe — Stripe is told the answer, it doesn't compute it.

3 · Your cost & margin — the internal reconciliation view

The cost_usd column is what Twilio charged you, per message. Monthly, per client: Stripe revenue − summed cost_usd − fixed (number $1.15 + campaign $1.50–$10) = net margin. That's the §04 worked-examples table, made live. Two things it catches that Twilio's dashboard won't:

• Reconcile summed cost_usd vs the actual Twilio invoice each month — a gap means the emoji/UCS-2 trap (§04) is silently inflating segments, or a template regressed to UCS-2.
• Delivered-vs-sent per client — a low delivery rate is 30007 carrier filtering: you're paying to send texts that never arrive. Surface it before the client notices.

4 · The ROI dashboard — Dashee shows the client the value

Dashee is the client-facing dashboard (per boundaries), so ROI reporting lives there — reading the same shared tables, joined to the app that owns each outcome. This is the renewal argument: not "you sent 800 texts," but "those texts produced X."

07Implementation guide — standing up the shared rail

The numbered path from zero to a live send, ordered so the compliance backbone exists before the first text goes out. Do not reorder. Estimates are engineering effort; the real clock is the 1–3 day 10DLC approval in step 2.

08Risks, honestly

09Bottom line