Initial prompt

Capture the first build prompt on your own storefront and have the customer's workspace open mid-build on their first login. Works through the WHMCS module's Prompt Box or a single field on platform-create.

The highest-converting onboarding you can build is: your visitor types the app they want on your site, orders a plan, and their very first login opens the editor with that app already building. The initial_prompt flow makes that a first-class platform feature — no glue code on the Swarmz side, whichever panel or stack you run.

Your storefront            Your billing            Swarmz platform
──────────────             ────────────            ───────────────
visitor types prompt  →    order + provision  →    platform-create { initial_prompt }
                                                        │ parked on the tenant
                                                   customer's FIRST login (sso)
                                                        │ first project auto-created
                                                        ▼ editor opens mid-build

Two ways to wire it

WHMCS — zero code

Module v1.9.0 ships an embeddable Prompt Box widget: one script tag on any page, a snippet builder with live preview in the Reseller Console, and automatic prompt hand-off through cart → checkout → provisioning.

Any stack — one field

Capture the prompt however you like (your own form, your panel, your funnel) and pass it as initial_prompt on platform-create. That is the entire integration.

WHMCS (native)

Install module v1.9.0+, open the Reseller Console's Prompt Box view, pick the product the widget should order, and paste the generated <script> tag into any page — plain HTML, WordPress, any builder. The widget stores the visitor's prompt against an opaque token, sends them into your WHMCS cart, and the module attaches the prompt to platform-create when the order provisions. Point it at a $0.00 instantly-activated product and you have the full "type a prompt → free instance spins up building it" funnel. Details and the embed attributes: WHMCS module → Prompt Box.

Plain Platform API

Send the captured prompt on platform-create:

curl -X POST https://api.swarmz.net/functions/v1/platform-create \
  -H "Authorization: Bearer sk_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "myhost:svc-871",
    "whu": { "email": "alice@example.com", "name": "Alice Martin" },
    "plan_code": "starter-monthly",
    "initial_prompt": "A booking site for my yoga studio with a class schedule and Stripe payments"
  }'

A true initial_prompt_pending in the response confirms the prompt is parked. That's the whole integration — the platform owns everything after this point.

Lifecycle and guarantees

Property	Behaviour
Storage	Parked on the tenant at provision time; trimmed, capped at 10,000 characters.
Consumption	On the customer's first entry (any SSO landing on their dashboard), the platform claims the prompt atomically, auto-creates their first project from it — same naming, limits and build pipeline as a hand-typed prompt — and drops them into the editor watching the build.
Exactly once	The claim is atomic: two tabs racing produce exactly one project. A failed creation (e.g. project cap) restores the prompt instead of losing it.
Retry-safe	A retried/duplicate `platform-create` can neither overwrite a still-pending prompt nor re-arm one that was already consumed.
Best-effort	A storage miss never fails provisioning; the customer simply lands on a normal empty dashboard.
Suspended tenants	Suspend blocks SSO entirely, so a pending prompt just waits for unsuspension.

The prompt is not built headlessly

Nothing is generated until the customer arrives — the build starts in their editor session, in front of them, spending their plan's credits exactly like a prompt they typed themselves. Provisioning a tenant with initial_prompt and never logging the customer in costs nothing.

Building your own prompt box

If you are not using the WHMCS widget, the capture UX is fully yours. Two practical notes:

Keep the prompt server-side between capture and provision. Prompts routinely exceed URL-length limits — store the text against your own order/session (the WHMCS module stores it as a tokenized "intent" for 30 days) and pass it in the platform-create body when you provision.
Plan selection is just product routing. Let the visitor pick a plan next to the prompt box and route the pair (prompt, plan) into your checkout; at provision time they become initial_prompt + plan_code.