Data Flow

Customer Journey:
  Website Form → N8N Webhook (popn-contact)
       OR
  Phone Call → Vonage → AI Voice Agent (Cartesia)
       ↓
┌─────────────────────────────────────┐
│         N8N Workflow Engine         │
├─────────────────────────────────────┤
│ POPN-webform (contact form)        │
│ POPN-create-booking                │
│ POPN-get-slots                     │
│ POPN-cancel-booking                │
│ POPN-payment-link (Stripe)         │
│ POPN-stripe-event (payment conf.)  │
│ POPN-voice-events                  │
│ POPN-config (config server)        │
└─────────────────────────────────────┘
       ↓                    ↓
  Google Calendar      Config Server
  (per performer)    (.POPN-variables.json)
       ↓
  Admin Portal (this app)
  - Pricing management
  - Performer management
  - SMS templates
  - Integration config

Tech Stack

Face Painting OR Balloon Twisting

1 artist provides the service. Same pricing for either service.

Bubble Party

Includes bubble machines, wands & pools. Outdoor recommended.

Caricatures OR Glitter Tattoos

1 artist. ⚠️ Caricatures NOT available in Houston region.

Live Glitter Fashion Drawing

1 artist. Premium service — no 1.5hr or 2.5hr options.

Travel Fee

• Flat $25 within 80-mile radius
• Radius measured from HQ (14201 Coyote Trail, Haslet TX) or assigned contractor's base location
• Beyond radius: contact for custom quote

Payment Structure

• Deposit: 30% non-refundable (unless Poppin' cancels → full refund)
• Final Balance: Remaining 70% collected 3 days before event
• Method: Stripe Payment Links sent via SMS

End-to-End Booking Process

Two-Stage Stripe Payment Links

Stage 1: Deposit
  Customer confirms → N8N creates Stripe Payment Link (30%)
  → Vonage sends SMS with link
  → Customer pays
  → Stripe webhook fires checkout.session.completed
  → N8N triggers "Booked" confirmation + calendar event

Stage 2: Final Balance (3 days before event)
  Scheduled N8N trigger
  → Creates Stripe link for remaining 70%
  → Vonage sends SMS with link + artist info
  → Customer pays
  → Stripe webhook confirms → event fully paid

Setup

• Create Stripe account for Poppin' Parties TX
• Add publishable key + secret key in Integrations tab
• Set up webhook endpoint: https://n8n.optimus.systems/webhook/popn-stripe-event
• Subscribe to event: checkout.session.completed

Payment Link API

N8N workflow creates payment links dynamically via POST /v1/payment_links with amount, description, and metadata (booking ID, customer name).

Phone Number

Vonage number: +1 (972) 777-6725

Capabilities

• SMS: Send/receive text messages (payment links, confirmations, reviews)
• Voice: Inbound call routing to AI agent, outbound lead follow-up

Overview

Bella is the Cartesia Line AI voice agent that handles inbound calls on +1 (972) 777-6725. She answers availability questions, quotes prices, creates/cancels bookings, and can transfer callers to team members via sequential ringing.

Capabilities

• Inbound: Answer availability questions, quote prices, take booking details, check calendar
• Booking: Create and cancel bookings via N8N workflows
• Pricing: Real-time quotes for all services and durations (1-8hr events)
• Transfer: Sequential ringing — rings performers in priority order per region

📞 Phone Routing Modes

Control how inbound calls are handled from the Phone Routing tab:

🔔 Sequential Ringing

When a call is transferred, the system rings team members one at a time:

1. On Call performer rings first (if set) — covers ALL regions
2. Regional priority performers ring in order (lower number = rings first)
3. Performers outside working hours are skipped (if "Respect working hours" is enabled)
4. Each performer rings for the configured Max Ring Time before trying the next
5. If nobody answers, the customizable No-Answer Message is spoken to the caller

How to Configure

1. Go to Phone Routing tab
2. Select a routing mode
3. Optionally set an On Call performer (rings first for all regions)
4. In the Regional Routing Priorities table, set priority numbers per region (1 = rings first, blank = skip)
5. Use arrow keys or type a number. Set to 0 or delete to clear a priority.
6. Click Save Changes

🔧 Technical Details

• Platform: Cartesia Line SDK v0.2.8 + Groq GPT-OSS (LLM)
• Voice: Jacqueline (Cartesia Sonic 3 TTS + Ink STT)
• Agent ID: agent_fSTWNXEz2wi7fqNoTEiBAB
• Phone: +1 (972) 777-6725 (Vonage Voice API)
• Transfer: Vonage NCCO sequential connect via HMAC-signed answer URL
• Deploy: cd cartesia-agent && ./deploy.sh

Overview

280 auto-generated city+service SEO landing pages across 3 regions. Generated by node generate-seo-pages.js. Do not hand-edit — they are overwritten by the generator.

Core Service Pages

Payment Status Colors

Calendar events automatically change color as payments are received:

How It Works

• New bookings are created with tangerine (unpaid)
• When Stripe fires checkout.session.completed, the POPN - Payment Received N8N workflow updates the event color and description
• Payment status is only visible to owners in the calendar description (artists see event details only)
• You can also manually record a payment via the webhook (see BOOKING-AUTOMATION-SYSTEM.md)

Core Integrations

Infrastructure

Getting Started

• Sign in with an authorized Google account (set in Admin Users tab)
• All changes auto-save after a 1.5s delay or when clicking Save
• The ⚡ indicator shows unsaved changes

Tabs Reference

Overview

The Messages tab is a two-way SMS inbox showing every text sent to or from +1 (972) 777-6725 — including booking confirmations, payment links, Bella's auto-replies, and customer responses. Admins can manually reply to any active conversation in real time.

📥 What Gets Logged

• Inbound — every SMS from a customer (received via Vonage webhook)
• Outbound — booking confirmations, payment link SMS, reminders (logged by N8N workflows)
• Bella replies — texts sent by the AI voice agent (tagged with 🤖 Bella)
• Admin replies — manual sends from this portal (tagged with admin email)
• Auto-replies — STOP/START/HELP keyword confirmations sent automatically

🚫 SMS Opt-Out Compliance (CTIA / 10DLC)

US carriers require all SMS senders — even transactional — to honor opt-out keywords. Failing to do so risks number suspension and 10DLC campaign revocation.

Disclosure Footer

The first SMS in any new conversation should include: "Reply STOP to opt out, HELP for help. Msg & data rates may apply." This is a CTIA best practice for all commercial SMS.

Using the Messages Tab

1. Conversations are listed in the left panel, sorted by most recent activity
2. Filters: All · Unread · Active · Opted Out
3. Search by customer name, phone, message text, or booking reference
4. Click a conversation to view the full thread
5. Type a reply at the bottom (Cmd/Ctrl+Enter to send)
6. Opted-out conversations are greyed out and the reply box is disabled — server enforces this regardless of UI state
7. Manual opt-out: click "🚫 Opt Out" in the thread header (e.g. customer requested verbally)
8. Re-enable: click "↻ Re-enable SMS" — only do this with documented customer consent (logged for compliance)

Email Compliance (CAN-SPAM)

Currently all email traffic is internal (notifications to admins/dispatch), so CAN-SPAM does not apply. If customer-facing email is ever added (booking confirmations to customers, marketing newsletters), the system will need:

• Unsubscribe link in every commercial email (10-day honor window)
• Valid physical postal address in footer
• Truthful "From" / subject lines
• The contact_opt_outs table is already designed with a channel column to support email opt-outs without a migration

FastAPI Backend Endpoints