From feb22885d0ef2ba18265129ef236c3bf4d97ed83 Mon Sep 17 00:00:00 2001
From: Nitheesh D R <nitheeraj1@gmail.com>
Date: Mon, 7 Sep 2026 21:36:25 +0530
Subject: [PATCH 1/2] PUL-16: minimal WhatsApp Cloud API pilot, for App Review

App Review's screencast and API-test-call requirements need a real,
working feature to demonstrate -- nothing in the Cloud API epic
(PUL-13 through PUL-20) existed in code yet, only Jira tracking and
Meta-side account setup.

This is a deliberately minimal, real slice: one working send
(whatsapp_business_messaging) and one working template list
(whatsapp_business_management), against Meta's own free test business
number (temporary token from the App Dashboard's API Setup page, in
.env.local, never committed). Not the merchant-facing send path --
that's PUL-18, gated on the billing decision (PUL-15) and template
workflow (PUL-17). Not reachable from the main sidebar nav.

- src/lib/whatsapp-cloud/client.ts: new, parallel to (not replacing)
  src/lib/whatsapp/client.ts's gateway client, per PUL-16's own scope
  note in the epic.
- src/app/api/whatsapp-cloud/{test-send,templates}: two thin routes,
  same requireTenant + hand-typed-recipient-only pattern as the
  existing /api/whatsapp/test route.
- src/app/(app)/whatsapp-cloud-pilot: one page to record the App
  Review screencast against.
- src/proxy.ts: added to PROTECTED_PAGES.
- src/lib/openapi.ts: both new routes documented, new tag added.

This is a partial slice of PUL-16's full scope (no webhook receiver,
no template-message sending yet) -- staying open after this merges,
not moving to Done.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 src/app/(app)/whatsapp-cloud-pilot/page.tsx   | 137 ++++++++++++++
 src/app/api/whatsapp-cloud/templates/route.ts |  26 +++
 src/app/api/whatsapp-cloud/test-send/route.ts |  52 ++++++
 src/lib/openapi.ts                            |  74 ++++++++
 src/lib/whatsapp-cloud/client.ts              | 170 ++++++++++++++++++
 src/proxy.ts                                  |   1 +
 6 files changed, 460 insertions(+)
 create mode 100644 src/app/(app)/whatsapp-cloud-pilot/page.tsx
 create mode 100644 src/app/api/whatsapp-cloud/templates/route.ts
 create mode 100644 src/app/api/whatsapp-cloud/test-send/route.ts
 create mode 100644 src/lib/whatsapp-cloud/client.ts

diff --git a/src/app/(app)/whatsapp-cloud-pilot/page.tsx b/src/app/(app)/whatsapp-cloud-pilot/page.tsx
new file mode 100644
index 0000000..b515c9b
--- /dev/null
+++ b/src/app/(app)/whatsapp-cloud-pilot/page.tsx
@@ -0,0 +1,137 @@
+"use client";
+
+import { Loader2, Send, ListChecks } from "lucide-react";
+import { useState } from "react";
+import { toast } from "sonner";
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import { Input } from "@/components/ui/input";
+import { Textarea } from "@/components/ui/textarea";
+
+interface CloudMessageTemplate {
+  id: string;
+  name: string;
+  status: string;
+  category: string;
+  language: string;
+}
+
+/**
+ * PUL-16 pilot: a minimal, real exercise of the Meta WhatsApp Cloud API,
+ * against the temporary test business number from the App Dashboard's own
+ * API Setup page — not the merchant-facing send path (that's PUL-18) and
+ * not reachable from the main sidebar nav. Exists so App Review's
+ * screencast requirement has a genuine, working flow to record: a real
+ * send via whatsapp_business_messaging, and a real template list via
+ * whatsapp_business_management.
+ */
+export default function WhatsAppCloudPilotPage() {
+  const [to, setTo] = useState("");
+  const [message, setMessage] = useState("Hello from the PulseCommerce Cloud API pilot.");
+  const [sending, setSending] = useState(false);
+
+  const [templates, setTemplates] = useState<CloudMessageTemplate[] | null>(null);
+  const [loadingTemplates, setLoadingTemplates] = useState(false);
+
+  const sendTest = async () => {
+    setSending(true);
+    try {
+      const res = await fetch("/api/whatsapp-cloud/test-send", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ to, message }),
+      });
+      const body = await res.json();
+      if (!res.ok) {
+        toast.error(body.error ?? "The send failed.");
+        return;
+      }
+      toast.success(`Sent — message id ${body.messageId}`);
+    } finally {
+      setSending(false);
+    }
+  };
+
+  const loadTemplates = async () => {
+    setLoadingTemplates(true);
+    try {
+      const res = await fetch("/api/whatsapp-cloud/templates", { cache: "no-store" });
+      const body = await res.json();
+      if (!res.ok) {
+        toast.error(body.error ?? "Could not list templates.");
+        return;
+      }
+      setTemplates(body.templates);
+    } finally {
+      setLoadingTemplates(false);
+    }
+  };
+
+  return (
+    <div className="mx-auto max-w-2xl space-y-6 p-6">
+      <Card>
+        <CardHeader>
+          <CardTitle className="flex items-center gap-2">
+            <Send className="size-4" /> Send a test message
+          </CardTitle>
+          <CardDescription>
+            Uses whatsapp_business_messaging against Meta&apos;s test business number. The
+            recipient must be one of the up to 5 numbers verified as a test recipient in the App
+            Dashboard.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-3">
+          <Input
+            placeholder="Recipient, e.g. 916383984698"
+            value={to}
+            onChange={(e) => setTo(e.target.value)}
+          />
+          <Textarea value={message} onChange={(e) => setMessage(e.target.value)} rows={3} />
+          <Button onClick={sendTest} disabled={sending || !to || !message}>
+            {sending ? <Loader2 className="size-4 animate-spin" /> : <Send className="size-4" />}
+            Send
+          </Button>
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle className="flex items-center gap-2">
+            <ListChecks className="size-4" /> Message templates
+          </CardTitle>
+          <CardDescription>
+            Uses whatsapp_business_management to list templates on the connected WhatsApp
+            Business Account.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-3">
+          <Button onClick={loadTemplates} disabled={loadingTemplates} variant="outline">
+            {loadingTemplates ? <Loader2 className="size-4 animate-spin" /> : <ListChecks className="size-4" />}
+            List templates
+          </Button>
+
+          {templates && (
+            <div className="space-y-2">
+              {templates.length === 0 ? (
+                <p className="text-sm text-muted-foreground">No templates on this account yet.</p>
+              ) : (
+                templates.map((t) => (
+                  <div
+                    key={t.id}
+                    className="flex items-center justify-between rounded-md border px-3 py-2 text-sm"
+                  >
+                    <span>
+                      {t.name} <span className="text-muted-foreground">({t.language})</span>
+                    </span>
+                    <Badge variant="outline">{t.status}</Badge>
+                  </div>
+                ))
+              )}
+            </div>
+          )}
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
diff --git a/src/app/api/whatsapp-cloud/templates/route.ts b/src/app/api/whatsapp-cloud/templates/route.ts
new file mode 100644
index 0000000..e76e6fb
--- /dev/null
+++ b/src/app/api/whatsapp-cloud/templates/route.ts
@@ -0,0 +1,26 @@
+import { NextResponse } from "next/server";
+import { requireTenant } from "@/lib/auth/tenant";
+import { listCloudMessageTemplates, WhatsAppCloudApiError } from "@/lib/whatsapp-cloud/client";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+/**
+ * PUL-16 pilot: lists message templates on the test WABA, using
+ * whatsapp_business_management. See test-send/route.ts's own comment for
+ * why this exists as a real, minimal, working call rather than nothing --
+ * App Review needs to see each permission actually exercised by the app.
+ */
+export async function GET(request: Request) {
+  const resolved = await requireTenant(request);
+  if (!resolved.ok) return resolved.response;
+
+  try {
+    const templates = await listCloudMessageTemplates();
+    return NextResponse.json({ templates });
+  } catch (error) {
+    const message =
+      error instanceof WhatsAppCloudApiError ? error.message : "Could not list message templates.";
+    return NextResponse.json({ error: message }, { status: 502 });
+  }
+}
diff --git a/src/app/api/whatsapp-cloud/test-send/route.ts b/src/app/api/whatsapp-cloud/test-send/route.ts
new file mode 100644
index 0000000..fbc0d2e
--- /dev/null
+++ b/src/app/api/whatsapp-cloud/test-send/route.ts
@@ -0,0 +1,52 @@
+import { NextResponse } from "next/server";
+import { z } from "zod";
+import { requireTenant } from "@/lib/auth/tenant";
+import { sendCloudTextMessage, WhatsAppCloudApiError } from "@/lib/whatsapp-cloud/client";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+const schema = z.object({
+  to: z.string().min(6),
+  message: z.string().min(1).max(4096),
+});
+
+/**
+ * PUL-16 pilot: one real send through Meta's Cloud API, using the temporary
+ * test token and test business number from the App Dashboard. Not the
+ * merchant-facing send path -- that's PUL-18, gated on the billing decision
+ * and template workflow. This exists so App Review has a real, working
+ * whatsapp_business_messaging call to review, not a mock.
+ *
+ * Deliberately no audience/customer-key input, same reasoning as
+ * /api/whatsapp/test: this can only ever message a number typed by the
+ * operator, never a customer pulled from store data.
+ */
+export async function POST(request: Request) {
+  const resolved = await requireTenant(request);
+  if (!resolved.ok) return resolved.response;
+
+  let body: unknown;
+  try {
+    body = await request.json();
+  } catch {
+    return NextResponse.json({ error: "Invalid JSON body." }, { status: 400 });
+  }
+
+  const parsed = schema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: parsed.error.issues.map((i) => i.message).join(" ") },
+      { status: 422 },
+    );
+  }
+
+  try {
+    const sent = await sendCloudTextMessage(parsed.data.to, parsed.data.message);
+    return NextResponse.json({ sent: true, messageId: sent.messageId });
+  } catch (error) {
+    const message =
+      error instanceof WhatsAppCloudApiError ? error.message : "The Cloud API rejected the send.";
+    return NextResponse.json({ error: message }, { status: 502 });
+  }
+}
diff --git a/src/lib/openapi.ts b/src/lib/openapi.ts
index 30952ef..a2b4fcf 100644
--- a/src/lib/openapi.ts
+++ b/src/lib/openapi.ts
@@ -80,6 +80,12 @@ export const openApiDocument = {
     { name: "Sync", description: "The local mirror of your WooCommerce store" },
     { name: "Billing", description: "Plans, usage, invoices and Razorpay subscriptions" },
     { name: "Order confirmations", description: "WhatsApp thank-you messages sent on new orders" },
+    {
+      name: "WhatsApp Cloud API pilot",
+      description:
+        "PUL-16: a minimal pilot against Meta's official Cloud API test business number, built " +
+        "for App Review. Not the merchant-facing send path.",
+    },
   ],
   paths: {
     "/api/sync": {
@@ -883,6 +889,74 @@ export const openApiDocument = {
       },
     },
 
+    "/api/whatsapp-cloud/test-send": {
+      post: {
+        tags: ["WhatsApp Cloud API pilot"],
+        summary: "Send one message via Meta's Cloud API test business number",
+        description:
+          "PUL-16 pilot, not the merchant-facing send path. Exercises whatsapp_business_messaging " +
+          "against the temporary test token and test business number from the App Dashboard's own " +
+          "API Setup page — never per-tenant credentials. Recipient must be one of the up to 5 " +
+          "numbers verified as a test recipient in the App Dashboard.",
+        requestBody: {
+          required: true,
+          content: json({
+            type: "object",
+            properties: {
+              to: { type: "string", example: "916383984698" },
+              message: { type: "string", maxLength: 4096 },
+            },
+            required: ["to", "message"],
+          }),
+        },
+        responses: {
+          200: {
+            description: "Sent",
+            content: json({
+              type: "object",
+              properties: { sent: { type: "boolean" }, messageId: { type: "string" } },
+            }),
+          },
+          422: errorResponse("Invalid recipient or message"),
+          502: errorResponse("The Cloud API rejected the send"),
+        },
+      },
+    },
+
+    "/api/whatsapp-cloud/templates": {
+      get: {
+        tags: ["WhatsApp Cloud API pilot"],
+        summary: "List message templates on the test WhatsApp Business Account",
+        description:
+          "PUL-16 pilot. Exercises whatsapp_business_management by resolving the test phone " +
+          "number's parent WABA and listing its message templates.",
+        responses: {
+          200: {
+            description: "Templates",
+            content: json({
+              type: "object",
+              properties: {
+                templates: {
+                  type: "array",
+                  items: {
+                    type: "object",
+                    properties: {
+                      id: { type: "string" },
+                      name: { type: "string" },
+                      status: { type: "string" },
+                      category: { type: "string" },
+                      language: { type: "string" },
+                    },
+                  },
+                },
+              },
+            }),
+          },
+          502: errorResponse("Could not list message templates"),
+        },
+      },
+    },
+
     "/api/ai/chat": {
       post: {
         tags: ["Assistant"],
diff --git a/src/lib/whatsapp-cloud/client.ts b/src/lib/whatsapp-cloud/client.ts
new file mode 100644
index 0000000..189fade
--- /dev/null
+++ b/src/lib/whatsapp-cloud/client.ts
@@ -0,0 +1,170 @@
+/**
+ * Meta WhatsApp Cloud API — a minimal pilot client, PUL-16.
+ *
+ * Deliberately parallel to src/lib/whatsapp/client.ts (the self-hosted
+ * gateway client), not a replacement for it yet — that migration is PUL-18,
+ * gated on the billing decision (PUL-15) and the template workflow (PUL-17).
+ * This exists to get one real, working send and one real template-list call
+ * through the actual app, using Meta's free test business number, so App
+ * Review has something genuine to screen-record rather than nothing.
+ *
+ * Auth here is a single temporary token from the App Dashboard's own API
+ * Setup page (~24h validity) via env vars — not a per-merchant Embedded
+ * Signup token. That's PUL-19; this pilot never touches per-tenant storage.
+ */
+
+const GRAPH_API_VERSION = "v21.0";
+
+export class WhatsAppCloudApiError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly endpoint: string,
+  ) {
+    super(message);
+    this.name = "WhatsAppCloudApiError";
+  }
+}
+
+interface CloudCredentials {
+  accessToken: string;
+  phoneNumberId: string;
+}
+
+function credentialsFromEnv(): CloudCredentials | null {
+  const accessToken = process.env.WHATSAPP_CLOUD_TEST_TOKEN?.trim();
+  const phoneNumberId = process.env.WHATSAPP_CLOUD_TEST_PHONE_NUMBER_ID?.trim();
+  if (!accessToken || !phoneNumberId) return null;
+  return { accessToken, phoneNumberId };
+}
+
+async function graphRequest<T>(
+  path: string,
+  accessToken: string,
+  init: { method?: string; body?: unknown } = {},
+): Promise<T> {
+  const url = `https://graph.facebook.com/${GRAPH_API_VERSION}/${path}`;
+  const res = await fetch(url, {
+    method: init.method ?? "GET",
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      ...(init.body ? { "Content-Type": "application/json" } : {}),
+    },
+    body: init.body ? JSON.stringify(init.body) : undefined,
+    cache: "no-store",
+  });
+
+  const text = await res.text();
+  if (!res.ok) {
+    let message = `Graph API request to ${path} failed (${res.status}).`;
+    try {
+      const parsed = JSON.parse(text);
+      if (parsed?.error?.message) message = parsed.error.message;
+    } catch {
+      // Body wasn't JSON — keep the generic message above.
+    }
+    throw new WhatsAppCloudApiError(message, res.status, path);
+  }
+
+  return text ? (JSON.parse(text) as T) : (undefined as T);
+}
+
+export interface CloudSentMessage {
+  messagingProduct: string;
+  waId: string;
+  messageId: string;
+}
+
+/**
+ * Sends a free-form text message via the Cloud API.
+ *
+ * Only valid within a 24h customer-service window (i.e. the recipient
+ * messaged this business number first) or, for this pilot, to one of the
+ * up to 5 numbers Meta lets you pre-verify as test recipients regardless of
+ * that window. A real merchant-facing send outside that window needs an
+ * approved template — see PUL-17, not built yet.
+ */
+export async function sendCloudTextMessage(to: string, body: string): Promise<CloudSentMessage> {
+  const creds = credentialsFromEnv();
+  if (!creds) {
+    throw new WhatsAppCloudApiError(
+      "WHATSAPP_CLOUD_TEST_TOKEN and WHATSAPP_CLOUD_TEST_PHONE_NUMBER_ID must both be set.",
+      0,
+      "messages",
+    );
+  }
+
+  const response = await graphRequest<{
+    messaging_product: string;
+    contacts: { wa_id: string }[];
+    messages: { id: string }[];
+  }>(`${creds.phoneNumberId}/messages`, creds.accessToken, {
+    method: "POST",
+    body: {
+      messaging_product: "whatsapp",
+      to,
+      type: "text",
+      text: { body },
+    },
+  });
+
+  return {
+    messagingProduct: response.messaging_product,
+    waId: response.contacts[0]?.wa_id ?? to,
+    messageId: response.messages[0]?.id ?? "",
+  };
+}
+
+export interface CloudMessageTemplate {
+  id: string;
+  name: string;
+  status: string;
+  category: string;
+  language: string;
+}
+
+/**
+ * Lists message templates on the connected WhatsApp Business Account —
+ * exercises whatsapp_business_management, separately from
+ * whatsapp_business_messaging above, since App Review reviews each
+ * permission's usage independently.
+ */
+export async function listCloudMessageTemplates(): Promise<CloudMessageTemplate[]> {
+  const creds = credentialsFromEnv();
+  if (!creds) {
+    throw new WhatsAppCloudApiError(
+      "WHATSAPP_CLOUD_TEST_TOKEN and WHATSAPP_CLOUD_TEST_PHONE_NUMBER_ID must both be set.",
+      0,
+      "message_templates",
+    );
+  }
+
+  // The template list lives on the WABA, not the phone number -- Meta's test
+  // setup exposes the phone number id directly, but message_templates is a
+  // WABA-level edge. The phone number lookup response includes its parent
+  // WABA id, so resolve that first rather than requiring a second env var.
+  const phoneInfo = await graphRequest<{ id: string; whatsapp_business_account?: { id: string } }>(
+    `${creds.phoneNumberId}?fields=whatsapp_business_account`,
+    creds.accessToken,
+  );
+  const wabaId = phoneInfo.whatsapp_business_account?.id;
+  if (!wabaId) {
+    throw new WhatsAppCloudApiError(
+      "Could not resolve the WhatsApp Business Account id for this phone number.",
+      0,
+      "message_templates",
+    );
+  }
+
+  const templates = await graphRequest<{
+    data: { id: string; name: string; status: string; category: string; language: string }[];
+  }>(`${wabaId}/message_templates`, creds.accessToken);
+
+  return templates.data.map((t) => ({
+    id: t.id,
+    name: t.name,
+    status: t.status,
+    category: t.category,
+    language: t.language,
+  }));
+}
diff --git a/src/proxy.ts b/src/proxy.ts
index 390091e..ee9429e 100644
--- a/src/proxy.ts
+++ b/src/proxy.ts
@@ -126,6 +126,7 @@ const PROTECTED_PAGES = [
   "/flows",
   "/abandoned-checkouts",
   "/order-confirmations",
+  "/whatsapp-cloud-pilot",
   "/menu",
   "/connect",
   "/onboarding",

From c841d31e658b0c761466f2c07d53c30ae1d0bb4c Mon Sep 17 00:00:00 2001
From: Nitheesh D R <nitheeraj1@gmail.com>
Date: Mon, 7 Sep 2026 22:26:23 +0530
Subject: [PATCH 2/2] PUL-16: fix silent non-delivery, add template send mode

Two real bugs found by actually testing against Meta's live API:

1. sendCloudTextMessage (free-form) only delivers within an open 24h
   customer-service window -- Meta's API accepts the call and returns
   a real message id outside that window, but never delivers it. A
   pre-verified test recipient is exempt from needing App-Review
   production access, but NOT from this window rule, which is
   universal. Confirmed by a real send that "succeeded" per the API
   response but never arrived.

2. listCloudMessageTemplates tried to resolve the WABA id from the
   phone number node via a `whatsapp_business_account` field that
   does not exist on that node ("(#100) Tried accessing nonexisting
   field"). There is no documented way to derive it from the phone
   number id -- it's a third env var now, read directly from the App
   Dashboard's "WhatsApp Business account ID" shown next to the test
   number.

Fix for (1): added sendCloudTemplateMessage, using the "hello_world"
template every WABA has pre-approved from creation -- delivers
reliably with no open-window requirement, same as real merchant sends
(order confirmations, campaigns) always will need. The pilot page and
route now default to template mode, with free-form text still
available and clearly labelled with the window caveat.

Fix for (2): WHATSAPP_CLOUD_TEST_WABA_ID env var, set directly rather
than derived.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 src/app/(app)/whatsapp-cloud-pilot/page.tsx   | 26 +++++-
 src/app/api/whatsapp-cloud/test-send/route.ts | 24 +++++-
 src/lib/openapi.ts                            | 11 ++-
 src/lib/whatsapp-cloud/client.ts              | 82 +++++++++++++++----
 4 files changed, 114 insertions(+), 29 deletions(-)

diff --git a/src/app/(app)/whatsapp-cloud-pilot/page.tsx b/src/app/(app)/whatsapp-cloud-pilot/page.tsx
index b515c9b..9ad87bb 100644
--- a/src/app/(app)/whatsapp-cloud-pilot/page.tsx
+++ b/src/app/(app)/whatsapp-cloud-pilot/page.tsx
@@ -7,6 +7,7 @@ import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
 import { Input } from "@/components/ui/input";
+import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs";
 import { Textarea } from "@/components/ui/textarea";
 
 interface CloudMessageTemplate {
@@ -27,6 +28,7 @@ interface CloudMessageTemplate {
  * whatsapp_business_management.
  */
 export default function WhatsAppCloudPilotPage() {
+  const [mode, setMode] = useState<"template" | "text">("template");
   const [to, setTo] = useState("");
   const [message, setMessage] = useState("Hello from the PulseCommerce Cloud API pilot.");
   const [sending, setSending] = useState(false);
@@ -40,14 +42,14 @@ export default function WhatsAppCloudPilotPage() {
       const res = await fetch("/api/whatsapp-cloud/test-send", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ to, message }),
+        body: JSON.stringify({ to, message, mode }),
       });
       const body = await res.json();
       if (!res.ok) {
         toast.error(body.error ?? "The send failed.");
         return;
       }
-      toast.success(`Sent — message id ${body.messageId}`);
+      toast.success(`Sent (${body.mode}) — message id ${body.messageId}`);
     } finally {
       setSending(false);
     }
@@ -82,13 +84,29 @@ export default function WhatsAppCloudPilotPage() {
           </CardDescription>
         </CardHeader>
         <CardContent className="space-y-3">
+          <Tabs value={mode} onValueChange={(v) => setMode(v as "template" | "text")}>
+            <TabsList>
+              <TabsTrigger value="template">Template (reliable)</TabsTrigger>
+              <TabsTrigger value="text">Free-form text</TabsTrigger>
+            </TabsList>
+          </Tabs>
+          {mode === "text" && (
+            <p className="text-xs text-muted-foreground">
+              Only delivers if the recipient has messaged this business number first, opening a
+              24h window — otherwise Meta accepts the call and returns a message id, but the
+              message is never actually delivered.
+            </p>
+          )}
+
           <Input
             placeholder="Recipient, e.g. 916383984698"
             value={to}
             onChange={(e) => setTo(e.target.value)}
           />
-          <Textarea value={message} onChange={(e) => setMessage(e.target.value)} rows={3} />
-          <Button onClick={sendTest} disabled={sending || !to || !message}>
+          {mode === "text" && (
+            <Textarea value={message} onChange={(e) => setMessage(e.target.value)} rows={3} />
+          )}
+          <Button onClick={sendTest} disabled={sending || !to || (mode === "text" && !message)}>
             {sending ? <Loader2 className="size-4 animate-spin" /> : <Send className="size-4" />}
             Send
           </Button>
diff --git a/src/app/api/whatsapp-cloud/test-send/route.ts b/src/app/api/whatsapp-cloud/test-send/route.ts
index fbc0d2e..b28dd6d 100644
--- a/src/app/api/whatsapp-cloud/test-send/route.ts
+++ b/src/app/api/whatsapp-cloud/test-send/route.ts
@@ -1,14 +1,23 @@
 import { NextResponse } from "next/server";
 import { z } from "zod";
 import { requireTenant } from "@/lib/auth/tenant";
-import { sendCloudTextMessage, WhatsAppCloudApiError } from "@/lib/whatsapp-cloud/client";
+import {
+  sendCloudTemplateMessage,
+  sendCloudTextMessage,
+  WhatsAppCloudApiError,
+} from "@/lib/whatsapp-cloud/client";
 
 export const runtime = "nodejs";
 export const dynamic = "force-dynamic";
 
 const schema = z.object({
   to: z.string().min(6),
-  message: z.string().min(1).max(4096),
+  message: z.string().min(1).max(4096).optional(),
+  // "template" reliably delivers business-initiated with no open-window
+  // requirement (confirmed the hard way -- a "text" send outside an open
+  // 24h window returns a real message id from Meta but is never actually
+  // delivered). Defaults to template for exactly that reason.
+  mode: z.enum(["template", "text"]).default("template"),
 });
 
 /**
@@ -41,9 +50,16 @@ export async function POST(request: Request) {
     );
   }
 
+  if (parsed.data.mode === "text" && !parsed.data.message) {
+    return NextResponse.json({ error: "message is required for a text send." }, { status: 422 });
+  }
+
   try {
-    const sent = await sendCloudTextMessage(parsed.data.to, parsed.data.message);
-    return NextResponse.json({ sent: true, messageId: sent.messageId });
+    const sent =
+      parsed.data.mode === "template"
+        ? await sendCloudTemplateMessage(parsed.data.to)
+        : await sendCloudTextMessage(parsed.data.to, parsed.data.message!);
+    return NextResponse.json({ sent: true, messageId: sent.messageId, mode: parsed.data.mode });
   } catch (error) {
     const message =
       error instanceof WhatsAppCloudApiError ? error.message : "The Cloud API rejected the send.";
diff --git a/src/lib/openapi.ts b/src/lib/openapi.ts
index a2b4fcf..de20e2c 100644
--- a/src/lib/openapi.ts
+++ b/src/lib/openapi.ts
@@ -897,16 +897,21 @@ export const openApiDocument = {
           "PUL-16 pilot, not the merchant-facing send path. Exercises whatsapp_business_messaging " +
           "against the temporary test token and test business number from the App Dashboard's own " +
           "API Setup page — never per-tenant credentials. Recipient must be one of the up to 5 " +
-          "numbers verified as a test recipient in the App Dashboard.",
+          "numbers verified as a test recipient in the App Dashboard. mode \"template\" (default) " +
+          "sends the pre-approved hello_world template, which delivers regardless of an open " +
+          "customer-service window; mode \"text\" sends free-form and only actually delivers " +
+          "within an open 24h window — confirmed the hard way that Meta's API accepts and returns " +
+          "a message id for a \"text\" send outside that window without ever delivering it.",
         requestBody: {
           required: true,
           content: json({
             type: "object",
             properties: {
               to: { type: "string", example: "916383984698" },
-              message: { type: "string", maxLength: 4096 },
+              message: { type: "string", maxLength: 4096, description: "Required when mode is \"text\"." },
+              mode: { type: "string", enum: ["template", "text"], default: "template" },
             },
-            required: ["to", "message"],
+            required: ["to"],
           }),
         },
         responses: {
diff --git a/src/lib/whatsapp-cloud/client.ts b/src/lib/whatsapp-cloud/client.ts
index 189fade..a9a616f 100644
--- a/src/lib/whatsapp-cloud/client.ts
+++ b/src/lib/whatsapp-cloud/client.ts
@@ -29,13 +29,15 @@ export class WhatsAppCloudApiError extends Error {
 interface CloudCredentials {
   accessToken: string;
   phoneNumberId: string;
+  wabaId: string | null;
 }
 
 function credentialsFromEnv(): CloudCredentials | null {
   const accessToken = process.env.WHATSAPP_CLOUD_TEST_TOKEN?.trim();
   const phoneNumberId = process.env.WHATSAPP_CLOUD_TEST_PHONE_NUMBER_ID?.trim();
   if (!accessToken || !phoneNumberId) return null;
-  return { accessToken, phoneNumberId };
+  const wabaId = process.env.WHATSAPP_CLOUD_TEST_WABA_ID?.trim() || null;
+  return { accessToken, phoneNumberId, wabaId };
 }
 
 async function graphRequest<T>(
@@ -78,11 +80,16 @@ export interface CloudSentMessage {
 /**
  * Sends a free-form text message via the Cloud API.
  *
- * Only valid within a 24h customer-service window (i.e. the recipient
- * messaged this business number first) or, for this pilot, to one of the
- * up to 5 numbers Meta lets you pre-verify as test recipients regardless of
- * that window. A real merchant-facing send outside that window needs an
- * approved template — see PUL-17, not built yet.
+ * Only actually delivered within an open 24h customer-service window (the
+ * recipient messaged this business number first) — confirmed the hard way:
+ * a pre-verified test recipient is exempt from needing App-Review-approved
+ * production access, but NOT from this window rule, which is universal. The
+ * Graph API still accepts the call and returns a real message id outside
+ * the window, so a 200 response here does not mean the message actually
+ * reached the recipient's phone. Real merchant sends (order confirmations,
+ * campaigns) are always business-initiated with no guaranteed open window,
+ * so they need sendCloudTemplateMessage below, not this — see PUL-17 for
+ * the full template-submission workflow, not built yet.
  */
 export async function sendCloudTextMessage(to: string, body: string): Promise<CloudSentMessage> {
   const creds = credentialsFromEnv();
@@ -115,6 +122,48 @@ export async function sendCloudTextMessage(to: string, body: string): Promise<Cl
   };
 }
 
+/**
+ * Sends an approved template message — the only kind that reliably
+ * delivers business-initiated, with no open-window requirement. Defaults
+ * to "hello_world", the fixed template every WABA has pre-approved from
+ * creation, specifically so a pilot/test send doesn't need PUL-17's
+ * template-submission workflow to exist first.
+ */
+export async function sendCloudTemplateMessage(
+  to: string,
+  templateName = "hello_world",
+  languageCode = "en_US",
+): Promise<CloudSentMessage> {
+  const creds = credentialsFromEnv();
+  if (!creds) {
+    throw new WhatsAppCloudApiError(
+      "WHATSAPP_CLOUD_TEST_TOKEN and WHATSAPP_CLOUD_TEST_PHONE_NUMBER_ID must both be set.",
+      0,
+      "messages",
+    );
+  }
+
+  const response = await graphRequest<{
+    messaging_product: string;
+    contacts: { wa_id: string }[];
+    messages: { id: string }[];
+  }>(`${creds.phoneNumberId}/messages`, creds.accessToken, {
+    method: "POST",
+    body: {
+      messaging_product: "whatsapp",
+      to,
+      type: "template",
+      template: { name: templateName, language: { code: languageCode } },
+    },
+  });
+
+  return {
+    messagingProduct: response.messaging_product,
+    waId: response.contacts[0]?.wa_id ?? to,
+    messageId: response.messages[0]?.id ?? "",
+  };
+}
+
 export interface CloudMessageTemplate {
   id: string;
   name: string;
@@ -139,18 +188,15 @@ export async function listCloudMessageTemplates(): Promise<CloudMessageTemplate[
     );
   }
 
-  // The template list lives on the WABA, not the phone number -- Meta's test
-  // setup exposes the phone number id directly, but message_templates is a
-  // WABA-level edge. The phone number lookup response includes its parent
-  // WABA id, so resolve that first rather than requiring a second env var.
-  const phoneInfo = await graphRequest<{ id: string; whatsapp_business_account?: { id: string } }>(
-    `${creds.phoneNumberId}?fields=whatsapp_business_account`,
-    creds.accessToken,
-  );
-  const wabaId = phoneInfo.whatsapp_business_account?.id;
-  if (!wabaId) {
+  // The template list lives on the WABA, not the phone number. Confirmed the
+  // hard way: the phone number node has no whatsapp_business_account field
+  // ("(#100) Tried accessing nonexisting field") -- there is no documented
+  // way to derive the WABA id from a phone number id via this node, so it's
+  // a third env var, read directly off the App Dashboard's WhatsApp Business
+  // account ID shown next to the test number.
+  if (!creds.wabaId) {
     throw new WhatsAppCloudApiError(
-      "Could not resolve the WhatsApp Business Account id for this phone number.",
+      "WHATSAPP_CLOUD_TEST_WABA_ID must be set (the WhatsApp Business account ID shown in the App Dashboard).",
       0,
       "message_templates",
     );
@@ -158,7 +204,7 @@ export async function listCloudMessageTemplates(): Promise<CloudMessageTemplate[
 
   const templates = await graphRequest<{
     data: { id: string; name: string; status: string; category: string; language: string }[];
-  }>(`${wabaId}/message_templates`, creds.accessToken);
+  }>(`${creds.wabaId}/message_templates`, creds.accessToken);
 
   return templates.data.map((t) => ({
     id: t.id,