334 lines
14 KiB
Markdown
334 lines
14 KiB
Markdown
# A2P Wizard - Complete Backend Architecture & Rebuild Guide
|
|
|
|
## What A2P Wizard Does (TL;DR)
|
|
|
|
A user fills out a simple form with basic business info. The backend:
|
|
1. **Generates a fully compliant landing page/website** branded to the client
|
|
2. **Creates screenshots** of the opt-in process on that website
|
|
3. **Produces a complete A2P 10DLC compliance packet** (descriptions, sample messages, opt-in flow documentation, screenshots)
|
|
4. **Outputs white-labeled documentation** the agency can copy/paste into their TCR campaign registration (via HighLevel, Twilio, etc.)
|
|
|
|
---
|
|
|
|
## PHASE 1: Form Intake
|
|
|
|
### Input Fields (from the live form at `/automated-setup-trial`)
|
|
|
|
| Field | Purpose |
|
|
|-------|---------|
|
|
| Your Name (Agency or Owner) | Agency contact — NOT the end client |
|
|
| Your Email | Agency email for delivery |
|
|
| Client LEGAL Business Name | Must match EIN exactly, no special chars |
|
|
| Client Business ADDRESS | Must match EIN paperwork |
|
|
| Client Support Email | Should match brand registration email |
|
|
| Client Business Phone | Client's contact number |
|
|
| Business Description (1-2 sentences) | Used to generate website content + campaign description |
|
|
| Logo Upload | Client logo (max 400px) for website branding |
|
|
| TCPA Compliance Checkbox | Legal CYA — confirms client meets requirements |
|
|
|
|
### Form Backend
|
|
- **reCAPTCHA v3** on the form (Google)
|
|
- Form submission triggers the automation pipeline (likely via webhook to n8n or similar)
|
|
|
|
---
|
|
|
|
## PHASE 2: Content Generation (AI + Automation)
|
|
|
|
This is the core engine. Based on the "Domains to Dollars" approach by Getting Automated:
|
|
|
|
### 2A. AI Content Generation
|
|
|
|
**Input:** Business name, description, address, phone, email, logo
|
|
**Engine:** LLM (Claude/GPT) via n8n workflow or direct API call
|
|
|
|
**AI generates all of the following from the business description:**
|
|
|
|
#### For the Landing Page/Website:
|
|
- **Hero section:** Title, subtitle, CTA button text
|
|
- **Business description:** Expanded from the 1-2 sentence input
|
|
- **Pain points section:** 3-4 industry-specific pain points the business solves
|
|
- **How It Works:** 3-step process description
|
|
- **FAQ section:** 4-6 relevant Q&As about the business
|
|
- **Testimonials/Social proof:** Generic but industry-appropriate
|
|
- **Footer text:** Copyright + business name
|
|
|
|
#### For the A2P Compliance Packet:
|
|
- **Campaign Description:** Who sends messages, who receives them, why (TCR requirement)
|
|
- **Sample Messages (2-3):**
|
|
- Appointment reminder with `[brackets]` for templated fields
|
|
- Promotional/marketing message with brand name
|
|
- At least 1 with opt-out language ("Reply STOP to unsubscribe")
|
|
- **Opt-in Flow Description:** How end-users consent (website form, in-person, etc.)
|
|
- **Opt-in Confirmation Message:** Under 160 chars, includes brand name, HELP, STOP, frequency, rates
|
|
- **Opt-out Confirmation Message:** Brand name + confirmation no more messages
|
|
- **Help Message:** Brand name + support contact info
|
|
- **Use Case Description:** Maps to TCR campaign types (Mixed, Marketing, etc.)
|
|
|
|
### 2B. JSON Config Generation
|
|
|
|
All generated content gets structured into a `config.json`:
|
|
|
|
```json
|
|
{
|
|
"businessName": "Naples Cleaning LLC",
|
|
"businessAddress": "123 Main St, Naples, FL 34102",
|
|
"businessPhone": "(239) 555-0123",
|
|
"businessEmail": "support@naplescleaning.com",
|
|
"logoUrl": "https://cdn.a2pwizard.com/logos/abc123.png",
|
|
|
|
"header": "Naples Cleaning LLC",
|
|
"icon": "broom",
|
|
"title": "Professional Cleaning Services in Naples, FL",
|
|
"description": "Naples Cleaning LLC provides reliable residential and commercial cleaning...",
|
|
"buttonText": "Book Your Cleaning Today",
|
|
"heroButtonLink": "#contact",
|
|
|
|
"painpointsTitle": "Why Choose Professional Cleaning?",
|
|
"painpoints": [
|
|
"<b>Time-Consuming DIY Cleaning:</b> Spend your weekends enjoying life...",
|
|
"<b>Inconsistent Results:</b> Professional-grade equipment and training...",
|
|
"<b>Health Concerns:</b> Deep cleaning eliminates allergens..."
|
|
],
|
|
|
|
"howItWorksTitle": "How It Works",
|
|
"howItWorksSteps": [
|
|
"Step 1: Book online or call us",
|
|
"Step 2: We arrive and clean",
|
|
"Step 3: Enjoy your spotless space"
|
|
],
|
|
|
|
"faqTitle": "Frequently Asked Questions",
|
|
"faqItems": [
|
|
{"question": "What areas do you serve?", "answer": "We serve Naples and surrounding areas..."},
|
|
{"question": "Are you insured?", "answer": "Yes, we are fully licensed and insured..."}
|
|
],
|
|
|
|
"footerText": "© 2026 Naples Cleaning LLC. All rights reserved.",
|
|
|
|
"optInForm": {
|
|
"enabled": true,
|
|
"consentText": "I consent to receive SMS notifications and alerts from Naples Cleaning LLC. Message frequency varies. Message & data rates may apply. Text HELP to (239) 555-0123 for assistance. Reply STOP to unsubscribe at any time.",
|
|
"privacyPolicyUrl": "/privacy-policy",
|
|
"termsUrl": "/terms-of-service"
|
|
},
|
|
|
|
"privacyPolicy": "...generated full privacy policy text...",
|
|
"termsOfService": "...generated full terms of service text...",
|
|
|
|
"a2pPacket": {
|
|
"campaignDescription": "Messages are sent by Naples Cleaning LLC to customers who have opted in via the company website. Messages include appointment confirmations, reminders, and occasional promotional offers about cleaning services in the Naples, FL area.",
|
|
"sampleMessages": [
|
|
"Naples Cleaning LLC: Your cleaning appointment is confirmed for [date] at [time]. Reply STOP to opt out.",
|
|
"Naples Cleaning LLC: Hi [name]! We have a special offer this month - 20% off deep cleaning services. Book at naplescleaning.com. Msg&data rates apply. Reply STOP to unsubscribe.",
|
|
"Naples Cleaning LLC: Reminder - your scheduled cleaning is tomorrow at [time]. Questions? Call (239) 555-0123. Reply HELP for help, STOP to opt out."
|
|
],
|
|
"optInFlowDescription": "End users opt in by visiting the Naples Cleaning LLC website and filling out the contact form. Users must check a non-pre-selected checkbox to consent to receiving SMS messages. The opt-in form includes disclosure language about message frequency, data rates, and opt-out instructions. Privacy Policy and Terms of Service links are provided at the bottom of the form. Website URL: https://naplescleaning.a2pwizard.com/contact",
|
|
"optInConfirmation": "You're now subscribed to Naples Cleaning LLC updates. Msg frequency varies. Msg&data rates may apply. Reply HELP for help, STOP to cancel.",
|
|
"optOutConfirmation": "You have been unsubscribed from Naples Cleaning LLC. You will not receive any more messages from this number.",
|
|
"helpMessage": "Naples Cleaning LLC: For help, visit naplescleaning.com or call (239) 555-0123. Reply STOP to opt out.",
|
|
"optInKeywords": "START, OPTIN, UNSTOP, IN",
|
|
"optOutKeywords": "STOP, UNSUBSCRIBE, END, QUIT, CANCEL",
|
|
"helpKeywords": "HELP, INFO"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## PHASE 3: Website Generation
|
|
|
|
### Tech Stack (from the GitHub repo: Getting-Automated/landing-page-generator)
|
|
|
|
**React app** with these pre-built components:
|
|
- `HeaderBar` — Business name + icon
|
|
- `LandingHeader` — Hero section with CTA, reviews, optional video
|
|
- `IndustryPainpoints` — Pain points + optional lead capture form (Tally)
|
|
- `HowItWorks` — 3-step process
|
|
- `SocialValidation` — Testimonials
|
|
- `FAQSection` — Expandable FAQ
|
|
- `SecondCTA` — Final call to action
|
|
- `FooterBar` — Copyright + links
|
|
|
|
**CRITICAL A2P COMPLIANCE PAGES** (these are what make the magic happen):
|
|
|
|
1. **Contact/Opt-in Page** — Form with:
|
|
- Name, email, phone fields
|
|
- **Non-pre-selected SMS consent checkbox** with full disclosure text
|
|
- Separate marketing consent checkbox (optional)
|
|
- Privacy Policy link in footer
|
|
- Terms of Service link in footer
|
|
|
|
2. **Privacy Policy page** (`/privacy-policy`) — Auto-generated, includes:
|
|
- Company name and contact info
|
|
- What data is collected
|
|
- **CRITICAL:** "No mobile information will be shared with third parties/affiliates for marketing/promotional purposes"
|
|
- How data is used
|
|
- Cookie policy
|
|
|
|
3. **Terms of Service page** (`/terms-of-service`) — Auto-generated, includes:
|
|
- SMS messaging terms
|
|
- Message frequency disclosure
|
|
- Data rates disclaimer
|
|
- Opt-out instructions
|
|
- HELP instructions
|
|
|
|
### Build Process
|
|
```
|
|
config.json → React app reads config → npm run build → static HTML/CSS/JS
|
|
```
|
|
|
|
### Deployment
|
|
- **AWS S3 + CloudFront** (original "Domains to Dollars" approach)
|
|
- OR custom subdomain hosting (a2pwizard likely uses their own infra)
|
|
- Each client gets a unique URL like `clientname.a2pwizard.com` or a custom domain
|
|
|
|
---
|
|
|
|
## PHASE 4: Screenshot Generation
|
|
|
|
This is the **key differentiator** — screenshots are the #1 reason A2P campaigns get rejected.
|
|
|
|
### What Screenshots Are Needed:
|
|
1. **Opt-in form screenshot** — Shows the contact form with the SMS consent checkbox, disclosure text, and Privacy Policy/ToS links visible
|
|
2. **Privacy Policy page screenshot** — Shows the live privacy policy page
|
|
3. **Terms of Service page screenshot** — Shows the live terms page
|
|
4. **Website homepage screenshot** — Shows the branded business website is real and functional
|
|
|
|
### How to Generate:
|
|
- **Puppeteer/Playwright** (headless browser)
|
|
- Navigate to the deployed website
|
|
- Take full-page screenshots of each critical page
|
|
- Crop/annotate to highlight opt-in elements
|
|
- Upload to publicly accessible storage (S3, Google Drive, HighLevel media library)
|
|
- Generate shareable URLs for each screenshot
|
|
|
|
### Screenshot Output Format:
|
|
- PNG files, clearly showing the opt-in flow
|
|
- Hosted at public URLs that TCR reviewers can access
|
|
- Typically 3-5 screenshots per client
|
|
|
|
---
|
|
|
|
## PHASE 5: Compliance Packet Assembly & Delivery
|
|
|
|
### What Gets Delivered to the Agency:
|
|
|
|
**A complete copy-paste packet containing:**
|
|
|
|
1. **Campaign Description** — Ready to paste into TCR/HighLevel campaign registration
|
|
2. **Message Flow / Opt-in Description** — Exactly how users consent, with website URL and screenshot URLs
|
|
3. **Sample Messages (2-3)** — With `[bracketed]` template fields, brand name, and opt-out language
|
|
4. **Opt-in Confirmation Message** — Under 160 chars
|
|
5. **Opt-out Confirmation Message** — With brand name
|
|
6. **Help Message** — With brand name + contact info
|
|
7. **Keywords** — Opt-in, opt-out, help keywords
|
|
8. **Screenshot URLs** — Publicly hosted images of opt-in flow
|
|
9. **Website URL** — Live, functional compliance website
|
|
10. **White-labeled export** — Agency branding, not A2P Wizard branding
|
|
|
|
### Delivery Method:
|
|
- Email to agency with all assets
|
|
- Possibly a dashboard/portal to download
|
|
- PDF export option for client handoff
|
|
|
|
---
|
|
|
|
## COMPLETE BACKEND PIPELINE (End to End)
|
|
|
|
```
|
|
[User fills form]
|
|
↓
|
|
[Webhook fires to automation engine (n8n)]
|
|
↓
|
|
[Logo uploaded to CDN/S3]
|
|
↓
|
|
[AI generates all content: website copy + A2P compliance text]
|
|
↓
|
|
[config.json assembled with all content + business info]
|
|
↓
|
|
[React app builds static site from config.json]
|
|
↓
|
|
[Static site deployed to hosting (S3/CloudFront or subdomain)]
|
|
↓
|
|
[Headless browser takes screenshots of deployed site]
|
|
↓
|
|
[Screenshots uploaded to public storage, URLs generated]
|
|
↓
|
|
[Compliance packet assembled (all text + screenshot URLs + website URL)]
|
|
↓
|
|
[Email sent to agency with complete packet + white-label export]
|
|
↓
|
|
[Agency copy/pastes everything into TCR/HighLevel campaign registration]
|
|
↓
|
|
[Campaign approved ✓]
|
|
```
|
|
|
|
---
|
|
|
|
## REBUILD TECH STACK RECOMMENDATION
|
|
|
|
### Option A: n8n-Based (Like Original)
|
|
- **Form:** Custom form or Tally → webhook
|
|
- **Automation:** n8n workflow
|
|
- **AI:** Claude API or OpenAI API
|
|
- **Website:** React static site generator (fork Getting-Automated template)
|
|
- **Screenshots:** Puppeteer/Playwright in n8n or Lambda
|
|
- **Hosting:** AWS S3 + CloudFront or Cloudflare Pages
|
|
- **Storage:** S3 for logos + screenshots
|
|
- **Delivery:** Email via SendGrid/SES
|
|
|
|
### Option B: All-in-One (Simpler)
|
|
- **Form + Backend:** Next.js API routes or Cloudflare Workers
|
|
- **AI:** Claude API
|
|
- **Website:** Dynamic server-rendered pages (no build step needed — just serve from config)
|
|
- **Screenshots:** Playwright on a serverless function
|
|
- **Hosting:** Cloudflare Workers/Pages (free tier generous)
|
|
- **Storage:** Cloudflare R2 for logos + screenshots
|
|
- **Delivery:** Email via Resend or SES
|
|
|
|
### Option C: Minimal/Fast MVP
|
|
- **Form:** Simple HTML form → serverless function
|
|
- **AI:** Single Claude API call generates everything
|
|
- **Website:** Server-rendered HTML template (no React build step)
|
|
- **Screenshots:** Playwright
|
|
- **Hosting:** Single VPS or Cloudflare Workers
|
|
- **Everything in one codebase**
|
|
|
|
---
|
|
|
|
## A2P COMPLIANCE REQUIREMENTS CHECKLIST
|
|
|
|
For the generated website to pass TCR review, it MUST have:
|
|
|
|
- [ ] Live, accessible website URL
|
|
- [ ] Business name prominently displayed
|
|
- [ ] Contact form with phone number field
|
|
- [ ] **SMS consent checkbox (NOT pre-selected, NOT required to submit)**
|
|
- [ ] Consent text with: program description, originating number, brand identity, opt-in language, fee disclosure, frequency disclosure, HELP instructions, STOP instructions
|
|
- [ ] Privacy Policy page (accessible, mentions no third-party sharing of mobile data)
|
|
- [ ] Terms of Service page (accessible, includes SMS terms)
|
|
- [ ] Links to Privacy Policy and ToS in form footer (NOT in checkbox text)
|
|
- [ ] Business email matching brand (not gmail for large corps)
|
|
- [ ] Consistent branding across website, sample messages, and campaign description
|
|
|
|
### Sample Messages Must:
|
|
- [ ] Include brand name in at least one
|
|
- [ ] Use `[brackets]` for templated fields
|
|
- [ ] Include opt-out language in at least one ("Reply STOP to unsubscribe")
|
|
- [ ] Match the registered use case (don't say "OTP" if registered as Marketing)
|
|
|
|
### Campaign Description Must:
|
|
- [ ] State who sends messages (brand name)
|
|
- [ ] State who receives messages (customers, opted-in users)
|
|
- [ ] State why messages are sent (purpose)
|
|
- [ ] Match the sample messages in intent
|
|
|
|
---
|
|
|
|
## KEY FILES/REPOS TO REFERENCE
|
|
|
|
- **Landing page React template:** https://github.com/Getting-Automated/landing-page-generator
|
|
- **n8n workflow pattern:** "Domains to Dollars" Part 1 (content generation)
|
|
- **HighLevel A2P best practices:** https://help.gohighlevel.com/support/solutions/articles/48001229784
|
|
- **TCR campaign requirements:** Brand registration + Campaign registration via The Campaign Registry
|