# 01 — Foundations (the accounts, before anything technical)

[← Back to README](README.md) · Next: [02-lead-form.md](02-lead-form.md)

---

Before a single line of code or a single dollar of ad spend, you need a handful of
accounts wired together correctly. This file is the boring-but-load-bearing part. Get
these right now and the rest of the build is smooth; get them wrong and you will be
chasing silent failures later (see [appendix-C-troubleshooting.md](appendix-C-troubleshooting.md)
for what "wrong" looks like in practice).

Nothing here requires coding. Most of it is signing up and clicking through setup
wizards. Where a step has a gotcha that bites people, it is flagged.

---

## How the pieces fit together

Think of it as three layers:

```
  ┌──────────────────────────────────────────────────────────────┐
  │  META (Facebook) side — where leads are born                   │
  │                                                                │
  │   Facebook Page ──── attached to ──── your Lead Ad + Form      │
  │        │                                                        │
  │        └── lives inside ──▶ Meta Business Manager              │
  │                                  │                              │
  │                                  ├── holds your Ad Account      │
  │                                  ├── holds a Meta App           │
  │                                  └── holds a System User ───┐   │
  └────────────────────────────────────────────────────────┐  │   │
                                                            │  │
                       never-expiring token ◀───────────────┘  │
                                  │                             │
  ┌───────────────────────────────┼─────────────────────────────┘
  │  YOUR side — where leads get handled                          │
  │                               ▼                               │
  │   Cloudflare Worker ── fetches lead, computes price ──┐       │
  │                                                       │       │
  │            ┌──────────────────────┬───────────────────┘       │
  │            ▼                      ▼                            │
  │     SMS provider           Formspree (optional)               │
  │     (texts the quote)      (emails you a backup copy)         │
  └──────────────────────────────────────────────────────────────┘
```

The **Meta side** produces leads. **Your side** receives and acts on them. The bridge
between them is a special never-expiring token, minted by the **System User** — that token
is the one thing in this whole guide most likely to break your engine if it is set up the
lazy way, so it gets its own section below and a full walkthrough in
[04-the-worker.md](04-the-worker.md).

---

## The accounts, one at a time

### 1. Facebook Page (required)

A business **Page** — not your personal Facebook profile. Ads run from a Page, and the
lead form attaches to a Page. If you already run any Facebook presence for your business,
you have this.

- Create at: facebook.com → **Pages → Create a Page** (or go straight to
  facebook.com/pages/create/). You fill a **Page name** and **Category** (both required) and
  an optional Bio, then click **Create Page**. Do this while using your personal Facebook
  profile: if Facebook is currently "acting as" another Page, switch back to your profile
  first, a Page cannot create a Page and the create screen will not load.
- You must be an **admin** of the Page.
- This is also the Page a lead sees as the "sender" of the ad, so name and brand it as
  your business.

> 🔧 **Customize:** Use your own business Page. Everything downstream (the form, the ad,
> the lead webhook) hangs off this one Page.

---

### 2. Meta Business portfolio (required, free)

**business.facebook.com** is the container that holds everything on the Meta side: your
ad account, your Page, your app, and your System User. Meta now calls this container a
**Business portfolio** (you will still see the older names "Business Manager" and "Business
account" in some places, they mean the same thing). Without it you cannot create a System
User, and without a System User you cannot get the durable token the engine needs.

- Create at: business.facebook.com → create a Business portfolio.
- Add your **Page** to it (**Meta Business Suite → Settings → Accounts → Pages**).
- Create or add an **Ad account** inside it (**Meta Business Suite → Settings → Accounts →
  Ad accounts**). Note its ID — it looks like `act_XXXXXXXXXXXXXXX`.

> ℹ️ **Two different Meta tools, do not mix them up.** **business.facebook.com**
> (Meta Business Suite, and the **Settings** gear inside it) is where you set up and hold the
> *accounts*: your Page, ad account, System User, and app. **adsmanager.facebook.com**
> (**Ads Manager**) is a separate tool where you actually build, launch, and watch the ads
> themselves, that is [Section 05](05-facebook-ad.md). You do the account setup in Business
> Suite here, then switch to Ads Manager later to run the campaign. Ads Manager is also
> reachable from the menu inside Business Suite, so it is easy to think they are one thing,
> they are not.

> Meta has migrated the old "Business Settings" into the **Settings** gear in Meta Business
> Suite (older accounts may still call it "Business Settings"; both open the same place, and
> the old `business.facebook.com/settings` URL auto-redirects to
> `business.facebook.com/latest/settings`).

> NeatNow example (use your own): ad account `act_1901764640543722`, Page ID
> `976943655503330`. These are shown only so you recognize the shape of the IDs.

---

### 3. A Meta App (required, free)

A **Meta App** (developers.facebook.com) does two jobs in this build:

1. It is what **receives the lead webhook** — the "new lead just came in" ping Facebook
   sends to your worker.
2. It is the app context under which you **mint the System User token**.

Steps (current Create App wizard):

- Go to developers.facebook.com → **My Apps** → **Create App**. Meta has replaced the old
  "pick an app type" screen with a short wizard: **App details → Use cases → Business →
  Requirements → Overview**.
- **App details:** name it something obvious like **"Lead Webhook"** and set a contact email.
- **Use cases:** the app only needs to receive the lead webhook and read leads, which you
  wire up in [04-the-worker.md](04-the-worker.md). The route that matches how NeatNow's app
  is actually set up is **Create an app without a use case** (a bare app ID you add the
  `leadgen` webhook and Leads Access to later). Meta also offers a ready-made
  **Capture & manage ad leads with Marketing API** use case if you prefer an on-rails setup.
- **Business:** connect the Business portfolio you created in step 2.
- You will come back to this app in [04-the-worker.md](04-the-worker.md) to point its
  webhook at your worker's URL and to generate the token.

> **Ignore older guides that say "choose the Business type."** That path still exists but is
> now buried under **Other → select an App Type**, and Meta labels it "This option is going
> away soon," so do not build on it. (NeatNow's own app predates the wizard and still shows
> **Type: None**, which is the same thing as "without a use case.")

> NeatNow example (use your own): the app is named "NeatNow Lead Webhook."

> 🔧 **Customize:** Name the app whatever you like; "Lead Webhook" keeps its purpose
> obvious a year from now.

---

### 4. The System User (required — this is the one that matters)

In **Meta Business Suite → Settings → Users → System users** (older accounts: "Business
Settings → Users → System Users"), create a System User. This is a non-human identity
inside your business whose **token never expires**. The worker uses that token to fetch
each lead's details from Facebook. (See [`appendix-D-visual-walkthrough.md`](appendix-D-visual-walkthrough.md)
for dated screenshots of these screens.)

Why this account is the one to get right:

> A normal user token (or a "page token" derived from your login) **dies the moment you
> change your Facebook password** — or when Meta forces a security reset, or after ~60
> days. When it dies, the worker keeps receiving leads but **silently drops every one of
> them**: no quote text to the lead, no alert to you, not even a backup. NeatNow lost two
> days of leads to exactly this. A System User token survives password changes and can be
> set to **never** expire.

You do **not** need to understand the exact permissions yet — the full token-minting
walkthrough (which permissions, the "Leads" task on the Page, the account-verification
prompt) lives in [04-the-worker.md](04-the-worker.md). For now, just create the System
User and know that it exists for this reason.

> NeatNow example (use your own): the System User is named "Conversions API System User."

---

### 5. Cloudflare account (required, free)

The engine itself is a small **Cloudflare Worker** — a bit of code that runs on
Cloudflare's free tier and ties everything together (receives the webhook, fetches the
lead, computes the price, sends the texts). The free tier covers far more traffic than any
small business will generate.

- Create at: cloudflare.com → Sign up (free).
- You (or your AI assistant) will use Cloudflare's `wrangler` command-line tool to deploy
  the worker and set its secrets. That is covered in [04-the-worker.md](04-the-worker.md).
- No custom domain or website is required — the worker gets a free `*.workers.dev` URL.

---

### 6. An SMS provider with a send API (required)

This is what actually **texts the quote** to the lead and the alert to you. You need a
provider that (a) gives you a business phone number and (b) has an API to send a message
programmatically.

This guide's worked example uses **Quo (formerly OpenPhone)**. OpenPhone officially
rebranded to Quo in September 2025; the domain is now **quo.com** and openphone.com
redirects to it.

- Sign up at the provider, pick/port a **business phone number**.
- Get an **API key** (Quo: workspace **Settings → API** tab; requires an **Owner or Admin**
  role). ([Quo API authentication docs](https://www.quo.com/docs/mdx/api-reference/authentication))
- You will store the API key and your "from" number as worker secrets later.

> 🔧 **Customize:** Any SMS provider with a send-message API works — Twilio, Telnyx,
> OpenPhone/Quo, etc. The worker sends a simple HTTP request to send a text; you (or your
> AI assistant) point it at your provider's send endpoint and set the API key. If you use
> something other than OpenPhone, that one HTTP call is the only worker code you need to
> adjust.

---

### 7. Formspree (optional, but mind Meta's 90-day limit)

**Formspree** is a no-backend way to get an **emailed backup copy of every lead**. The
worker posts each lead to a Formspree form endpoint, and Formspree emails it to you. It is
a safety net: even if you miss a text, there is an out-of-band record.

Why bother, when Meta's Leads Center stores every lead your form captures? Because Leads
Center is **not** a permanent archive. Per Meta, instant-form leads are only available to
download for **90 days from submission**; after that Meta removes them and they cannot be
retrieved (this is true even for a campaign's lifetime results). So without a backup, the
real fallback is: if your worker ever goes down, you have up to 90 days to notice — the
fail-loud SMS alert ([04-the-worker.md](04-the-worker.md)) helps — and pull those leads from
Leads Center by hand. Past that window, un-retrieved leads are gone. An out-of-band backup
like Formspree gives you a lasting record.

> Source: Meta Business Help Center, *"About expired leads"* — "Leads data will be available for
> download for up to 90 days from the time the Instant Forms is submitted by a user."

- Create at: formspree.io (free tier is plenty).
- Create a form, copy its endpoint URL, and set it as a worker secret later.
- Entirely optional — skip it and the engine still runs fine; just treat Leads Center as a
  90-day window, not forever.

---

### 8. A payment method on the Meta ad account (required to spend)

Ads do not deliver without billing set up. In **Meta Business Suite → Settings → Billing &
payments** (or Ads Manager → Billing), add a payment method to your ad account. You will not be
charged until your ad is live and delivering; you control the budget. Details on the ad
itself are in [05-facebook-ad.md](05-facebook-ad.md).

---

## Accounts checklist

| Account | What it is for | Free or paid |
|---|---|---|
| **Facebook Page** | Ads and the lead form attach to it | Free |
| **Meta Business portfolio** | Container for the ad account, Page, app, and System User | Free |
| **Meta App** ("Lead Webhook") | Receives the lead webhook; context for minting the token | Free |
| **System User** | Identity whose never-expiring token the worker uses to fetch leads | Free |
| **Cloudflare** | Hosts the worker (the engine) | Free tier |
| **SMS provider** (Quo, formerly OpenPhone, etc.) | Sends the quote text and your owner alert | Monthly subscription + usage-based message credit |
| **Formspree** *(optional)* | Emails you a backup copy of every lead | Free tier |
| **Payment method on ad account** | Pays for ad delivery | Your ad budget |

So beyond ad spend, the only running cost of the stack is your SMS provider, and it has two
parts: a **monthly subscription** plus a **usage-based message credit** that draws down as you
send texts and gets topped up when it runs low. Budget for both, and check the provider's
current pricing for exact figures.

---

## Honest gap note

The exact signup screens for the **SMS provider** and for any **booking/CRM system** you
later follow up in change often, and they differ by provider, so this guide does **not**
reproduce them click-by-click. Treat "sign up and grab your API key" as a self-serve step
and follow the provider's own current docs:

- OpenPhone/Quo API: their Settings → API page and developer docs.
- Whatever booking or CRM tool you use to close leads is **your own manual follow-up
  destination and is out of scope here** — this guide stops at the automated quote text.

The Meta-side accounts (Page, Business portfolio, App, System User) are documented in detail
because their setup is where the load-bearing token gotcha lives, and getting it right is
the difference between a reliable engine and the silent-failure incident in
[appendix-C-troubleshooting.md](appendix-C-troubleshooting.md).

---

With the accounts in place, move on to designing the form that captures exactly what the
quote needs: **[02-lead-form.md](02-lead-form.md)**.
