@flowapt/flowiq-cli 0.7.3 → 0.7.4

package/README.md

@@ -193,7 +193,7 @@ flowiq ct list
 - **Retailer gateway credential:** `{{retailer_tools_internal_key}}` is super-admin-only and resolves only as the `x-api-key` value for `https://express.chatcart.io/retailer-tools/*` (or loopback in local tests). Validation and runtime both reject putting it in a body or sending it to any other host.
 - `--agent` + filenames behave like `prompts`/`knowledge`; the file carries `agent_id`, so `push` targets the agent it was pulled from.
 
-### Broadcast — `flowiq broadcast map|preview|send|resume|list-remote|status|retry|list` (alias `bc`)
+### Broadcast — `flowiq broadcast map|preview|send|resume|list-remote|status|route|retry|list` (alias `bc`)
 
 Send an **APPROVED** WhatsApp template to every row of a CSV, filling the
 template's variables **per row** from the CSV's own columns. The
@@ -237,6 +237,16 @@ flowiq bc scheduled list <org_id>                   # open rows (pending + await
 flowiq bc scheduled list <org_id> --all             # incl. fired / cancelled
 flowiq bc scheduled approve <org_id> <queue_id>     # 'request' → 'pending' (--at re-times it)
 flowiq bc scheduled cancel  <org_id> <queue_id> --confirm
+
+# REPLY ROUTING (v0.7.4): assign EVERY reply to this broadcast to a team / person.
+flowiq bc send <org_id> --tag <batch-tag> --template <name> --body param1="…" \
+  --route-team "Spa" --commit                       # typed replies AND button taps → the Spa team
+flowiq bc send … --route-team "Spa" --route-member kim@client.com --route-window 48h --no-route-notify
+flowiq bc send … --csv people.csv --campaign 17Sep_Spa --route-team "Spa" --at "2026-09-18 09:00" --commit
+
+flowiq bc route <org_id> <broadcastId>                                   # show what a broadcast routes to + how many chats it has routed
+flowiq bc route <org_id> <broadcastId> --team "Spa" --commit             # set it on a broadcast that already went out
+flowiq bc route <org_id> <broadcastId> --clear --commit                  # switch it off
 ```
 
 - **Scheduling (v0.4.4 tag / v0.6.1 CSV)** — `--at "YYYY-MM-DD HH:MM"` queues the
@@ -295,6 +305,37 @@ flowiq bc scheduled cancel  <org_id> <queue_id> --confirm
   template. In **tag mode the campaign slug defaults to the tag**, so to send
   template A then template B to the SAME tag, pass a distinct `--campaign` for
   each. `resume` passes no `--template`, so it is never affected.
+- **Reply routing — `--route-team` / `--route-member` on `send`, and `bc route` (v0.7.4)**:
+  "every reply to this broadcast goes to team X / person Y". The first message a
+  recipient sends inside the window (default **72 h** after the send, `--route-window
+  48h|3d`, max 14 d) assigns the chat — **once per recipient per broadcast** — and
+  notifies the target through the normal assignment notification (the Teams-page
+  notify settings + the org's two notification flags still decide whether anything is
+  actually sent; `--no-route-notify` assigns silently). It is the fix for the gap a
+  quick-reply button + exact keyword + `assign_chat` cannot close: that route only
+  catches button TAPS, and a broad keyword mutes the AI agent. Routing is a side
+  effect — **keywords and the AI agent answer exactly as they would have**, and it
+  also applies to a chat whose agent is switched off. Skipped: business auto-replies
+  ("thank you for contacting…", out of office) and opt-outs (`stop`). An internal
+  note in the chat says why it was assigned. **An existing assignment is
+  overwritten**, same as the keyword action.
+  - `--route-team` takes a team name (case-insensitive; a unique partial match is
+    fine) or id; `--route-member` takes an email, a name or an id and must be an
+    ACTIVE member of that org. A typo stops the run in the **dry run** with the org's
+    teams listed — nothing is tagged, queued or sent.
+  - The routing is stored on the broadcast (`broadcasts.reply_routing`), so it
+    **forces the python engine at any size** (the per-row Node engine writes one
+    broadcast per recipient). Works in tag mode, CSV mode and with `--at` (the queued
+    send carries it and it is applied the moment the send fires).
+  - After a commit the CLI prints `Replies → … ✓ saved`. If it prints **REPLY ROUTING
+    NOT SAVED / NOT CONFIRMED**, the messages still went out — fix it straight away
+    with `bc route <org> <broadcastId> --team … --commit`.
+  - `bc route` with no flags shows the current routing and how many chats it has
+    routed; with `--team/--member` sets it; `--clear` removes it. Dry-run unless
+    `--commit`, audited. Only replies arriving AFTER the change are routed — nothing
+    is applied retroactively. `bc status` prints the routing too.
+  - Using routing AND a button keyword with `assign_chat` on the same campaign is
+    harmless but notifies twice on a tap — drop the keyword's assign when routing is on.
 - **`list-remote <org>` (v0.3.9)**: list the org's broadcasts **newest-first** with
   the **full broadcastId** per row + template, status, recipient count and SAST
   created time — the discovery step `status` / `retry` need (previously the id

package/TEAM-GUIDE.md

@@ -172,6 +172,8 @@ several.
 | Check how a broadcast is landing (accepted → delivered → read, plus failed/pending) | `flowiq bc status <org_id> <broadcastId>` (from the send output, or `bc list-remote`) |
 | See WHO failed on a broadcast + why (Meta error) | `flowiq bc status <org_id> <broadcastId> --failures` |
 | Re-send a broadcast to only the ones that failed | `flowiq bc retry <org_id> <broadcastId>` (dry-run) → `… --commit` |
+| Make EVERY reply to a broadcast land with a team or a person (client asks "all replies to the Spa team") | Add `--route-team "Spa"` (and/or `--route-member kim@client.com`) to the `bc send`. The first reply from each recipient within 72 hours (`--route-window 48h` to change) assigns the chat and notifies them, typed replies and button taps alike. The AI agent and keywords still answer as normal, so nothing is muted. The dry run shows `Replies → team Spa …`; a wrong team name stops the run and lists the org's teams. Works with `--csv` and `--at` too. |
+| Add, check or remove that routing on a broadcast that already went out | `flowiq bc route <org_id> <broadcastId>` shows it and how many chats it has routed · `… --team "Spa" --commit` sets it · `… --clear --commit` removes it. Only replies from now on are affected. |
 | **Get an OLD version of a prompt back** | `flowiq prompts history <org_id>` (pick the version) → `flowiq prompts restore <org_id> <audit_id>` (dry-run) → `… --commit` |
 | **See who changed what, and when** | `flowiq audit <org_id>` — add `--endpoint prompts`, `--user <name>`, `--since 2026-07-01` to narrow |
 | See exactly what a change looked like (before → after) | `flowiq audit show <audit_id> --content` (or `--out entry.json`) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.7.3",
+  "version": "0.7.4",
   "description": "Command-line tool for FlowIQ staff: round-trip agent prompts, questionnaires, fine-tuning, pin-board tasks, webhooks, templates, agent-updates, chat exports, and live agent testing without ever touching service-role credentials.",
   "type": "module",
   "bin": {

package/src/commands/broadcast.js

@@ -944,6 +944,10 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
     }
   }
 
+  // Reply routing: resolved before the dry-run exit so the preview shows it, and
+  // before the upsert so a bad team name never tags a single contact.
+  const replyRouting = isResume ? null : await checkRouting(orgId, opts);
+
   if (!commitStage) {
     console.log("");
     console.log(`DRY RUN — nothing was ${scheduledAt ? "scheduled" : "sent"}, no contacts written or tagged. Add --commit to ${scheduledAt ? "queue it" : "send"}.`);
@@ -968,6 +972,7 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
     body_parameters: tokens.body,
     ...(tokens.button ? { button_parameters: { param1: tokens.button } } : {}),
     ...(headerMedia ? { header_media: headerMedia } : {}),
+    ...(replyRouting ? { reply_routing: replyRouting } : {}),
     dry_run: dryRun,
   });
   let pyTotal = null;
@@ -1013,6 +1018,7 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
         body_parameters: tokens.body,
         ...(tokens.button ? { button_parameters: { param1: tokens.button } } : {}),
         ...(headerMedia ? { header_media: headerMedia } : {}),
+        ...(replyRouting ? { reply_routing: replyRouting } : {}),
       });
     } catch (e) {
       console.error(`Schedule failed: ${e.message}${e.body?.error ? ` — ${e.body.error}` : ""}`);
@@ -1035,6 +1041,10 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
       console.log(`      flowiq bc scheduled approve ${orgId} ${resp.queue_id}`);
     }
     console.log(`  Also visible/manageable on the dashboard's Scheduled sends page.`);
+    if (replyRouting) {
+      if (resp.reply_routing?.saved) console.log(`  Replies → ${describeRouting(resp.reply_routing.requested)}  ✓ queued with the send (applied the moment it fires)`);
+      else console.log(`  ⚠ REPLY ROUTING NOT CONFIRMED by the server — set it after it fires with: flowiq bc route ${orgId} <broadcast_id> --team … --commit`);
+    }
     return;
   }
 
@@ -1052,6 +1062,7 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
   console.log(`   Python is sending in the background to tag "${tag}" (${pyTotal ?? workSet.length} contact(s)) and tracking it under that broadcast id.`);
   console.log(`   Delivery:  flowiq bc status ${orgId} ${out.broadcastId || "<broadcast_id>"} [--failures]`);
   console.log(`   Failures:  flowiq bc retry  ${orgId} ${out.broadcastId || "<broadcast_id>"} --commit`);
+  if (replyRouting) reportRoutingResult(orgId, out.reply_routing, out.broadcastId ?? out.broadcast_id ?? null);
 }
 
 /** The paced, write-ahead-logged per-row send loop + final report. */
@@ -1146,13 +1157,98 @@ export function collectKV(pair, mapAcc) {
  *  (allow_broadcast=true, not blocked) and sends in the background, returning a
  *  broadcastId. No CLI write-ahead log / resume for this engine (python owns the
  *  broadcast record). Dry-run (no --commit) asks python for the eligible count. */
-async function runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage, cardOverrides = null, cardLines = [] }) {
+// ── Reply routing (v0.7.4) ───────────────────────────────────────────────────
+// `--route-team` / `--route-member` = "assign every reply to this broadcast to …".
+// The server resolves names → ids, stores it on the broadcast, and the agent runtime
+// applies it once per recipient inside the window WITHOUT muting keywords or the AI.
+
+/** "72" | "72h" | "3d" → whole hours, or { error }. */
+export function parseRouteWindow(input) {
+  if (input === undefined || input === null || input === "") return { hours: null };
+  const m = String(input).trim().toLowerCase().match(/^(\d{1,4})\s*(h|hr|hrs|hours?|d|days?)?$/);
+  if (!m) return { error: `"${input}" is not a window — use hours or days, e.g. 72, 72h or 3d` };
+  const n = Number(m[1]);
+  const hours = m[2] && m[2].startsWith("d") ? n * 24 : n;
+  if (hours < 1 || hours > 336) return { error: `the window must be between 1 hour and 14 days (got ${hours} h)` };
+  return { hours };
+}
+
+/** The send flags → the request's reply_routing object (null when no routing asked for). */
+export function routingFromOpts(opts = {}, keys = { team: "routeTeam", member: "routeMember", window: "routeWindow", notify: "routeNotify" }) {
+  const team = typeof opts[keys.team] === "string" ? opts[keys.team].trim() : "";
+  const member = typeof opts[keys.member] === "string" ? opts[keys.member].trim() : "";
+  const hasWindow = opts[keys.window] !== undefined && opts[keys.window] !== null && opts[keys.window] !== "";
+  const noNotify = opts[keys.notify] === false;
+  if (!team && !member) {
+    if (hasWindow || noNotify) return { error: "the routing window / no-notify flags need a team or a member to route to" };
+    return { routing: null };
+  }
+  const win = parseRouteWindow(opts[keys.window]);
+  if (win.error) return { error: win.error };
+  return {
+    routing: {
+      ...(team ? { team } : {}),
+      ...(member ? { member } : {}),
+      ...(win.hours ? { window_hours: win.hours } : {}),
+      ...(noNotify ? { notify: false } : {}),
+    },
+  };
+}
+
+export function describeRouting(d) {
+  if (!d) return "none";
+  const who = [d.team_name ? `team ${d.team_name}` : null, d.member_name || d.member_email || null].filter(Boolean).join(" + ") || "(unnamed target)";
+  const notes = [];
+  if (d.team_name) notes.push(d.notify_team === false ? "team not notified" : "team notified");
+  if (d.member_name || d.member_email) notes.push(d.notify_member === false ? "person not notified" : "person notified");
+  return `${who} · first reply within ${d.window_hours ?? 72} h · ${notes.join(", ")}`;
+}
+
+/** Resolve the routing on the server BEFORE anything is tagged, queued or sent. Exits on a bad team/member. */
+async function checkRouting(orgId, opts) {
+  const parsed = routingFromOpts(opts);
+  if (parsed.error) { console.error(`Error: ${parsed.error}`); process.exit(1); }
+  if (!parsed.routing) return null;
+  let resp;
+  try { resp = await http.post("broadcast", { action: "resolve-routing", organization_id: orgId, reply_routing: parsed.routing }); }
+  catch (e) {
+    console.error(`Reply routing refused: ${e.body?.error || e.message}`);
+    if (/unknown action|Unknown action|not supported/i.test(String(e.body?.error || "")) || e.status === 404) {
+      console.error("  (the server does not know reply routing yet — run `flowiq doctor`)");
+    }
+    process.exit(1);
+  }
+  if (!resp?.reply_routing) {
+    console.error("Reply routing refused: the server did not confirm it (it may predate v0.7.4 — run `flowiq doctor`). Nothing sent.");
+    process.exit(1);
+  }
+  console.log(`Replies →    ${describeRouting(resp.reply_routing)}`);
+  console.log(`             (assigned once per recipient; keywords and the AI agent still answer as normal)`);
+  return parsed.routing;
+}
+
+/** After a commit: say plainly whether the routing landed. */
+function reportRoutingResult(orgId, rr, broadcastId) {
+  if (!rr) {
+    console.log("   ⚠ REPLY ROUTING NOT CONFIRMED by the server — replies will NOT be assigned.");
+    if (broadcastId) console.log(`     Fix now: flowiq bc route ${orgId} ${broadcastId} --team … --commit`);
+    return;
+  }
+  if (rr.saved) console.log(`   Replies → ${describeRouting(rr.requested)}  ✓ saved`);
+  else {
+    console.log(`   ⚠ REPLY ROUTING NOT SAVED: ${rr.error || "unknown reason"}`);
+    if (broadcastId) console.log(`     Fix now: flowiq bc route ${orgId} ${broadcastId} --team … --commit`);
+  }
+}
+
+async function runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage, cardOverrides = null, cardLines = [], replyRouting = null }) {
   const reqBody = (dryRun) => ({
     action: "send-python", organization_id: orgId, tag, template_name: templateName,
     body_parameters: bodyLiterals,
     ...(buttonLiteral ? { button_parameters: { param1: buttonLiteral } } : {}),
     ...(headerMedia ? { header_media: headerMedia } : {}),
     ...(cardOverrides ? { card_overrides: cardOverrides } : {}),
+    ...(replyRouting ? { reply_routing: replyRouting } : {}),
     dry_run: dryRun,
   });
 
@@ -1189,6 +1285,7 @@ async function runPythonTagSend(orgId, { opts, tag, templateName, template, head
   console.log("");
   console.log(`✅ ${out.message || "Broadcast started"}${out.broadcastId ? `  ·  broadcastId ${out.broadcastId}` : ""}`);
   console.log(`   Python is sending in the background${out.mode ? ` (${out.mode})` : ""} and tracking it under that broadcast id — no CLI resume for this engine.`);
+  if (replyRouting) reportRoutingResult(orgId, out.reply_routing, out.broadcastId ?? out.broadcast_id ?? null);
 }
 
 async function runTagPipeline(orgId, opts, { commitStage }) {
@@ -1259,7 +1356,11 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
   const cardOverrides = carouselPlan?.overrides ?? null;
   const cardLines = carouselPlan?.lines ?? [];
 
-  if (opts.at) return scheduleTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage, cardOverrides, cardLines });
+  // Reply routing is resolved HERE — after the template checks, before any engine is
+  // picked — so a mistyped team stops the run in the dry run, not after a send.
+  const replyRouting = await checkRouting(orgId, opts);
+
+  if (opts.at) return scheduleTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage, cardOverrides, cardLines, replyRouting });
 
   // ENGINE ROUTING (policy): any send of MORE THAN 10 recipients ALWAYS uses the
   // python /meta-broadcast engine (the proven bulk sender). --python forces it at
@@ -1270,8 +1371,13 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
   if (template.is_carousel && !opts.python) {
     console.log("Carousel template → PYTHON engine at any size (the per-row Node engine cannot send carousels).");
   }
-  if (opts.python || template.is_carousel) {
-    return runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage, cardOverrides, cardLines });
+  // Reply routing lives on ONE broadcasts row, which only the python engine creates per
+  // send (the per-row Node engine writes a row per recipient) → python at any size.
+  if (replyRouting && !opts.python && !template.is_carousel) {
+    console.log("Reply routing → PYTHON engine at any size (the routing is stored on the single broadcast python creates).");
+  }
+  if (opts.python || template.is_carousel || replyRouting) {
+    return runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage, cardOverrides, cardLines, replyRouting });
   }
 
   // resolve the tag server-side (broadcast-safe recipients only). A >2000 tag
@@ -1433,7 +1539,7 @@ const fmtSast = (iso) =>
   new Date(iso).toLocaleString("en-ZA", { timeZone: "Africa/Johannesburg", dateStyle: "medium", timeStyle: "short" });
 
 /** Queue a tag broadcast to fire later (server writes the api_request_queue row). */
-async function scheduleTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage, cardOverrides = null, cardLines = [] }) {
+async function scheduleTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage, cardOverrides = null, cardLines = [], replyRouting = null }) {
   const when = parseSastAt(opts.at);
   if (when.error) { console.error(`Error: --at ${when.error}`); process.exit(1); }
   if (new Date(when.iso).getTime() <= Date.now()) {
@@ -1475,6 +1581,7 @@ async function scheduleTagSend(orgId, { opts, tag, templateName, template, heade
       ...(buttonLiteral ? { button_parameters: { param1: buttonLiteral } } : {}),
       ...(headerMedia ? { header_media: headerMedia } : {}),
       ...(cardOverrides ? { card_overrides: cardOverrides } : {}),
+      ...(replyRouting ? { reply_routing: replyRouting } : {}),
     });
   } catch (e) {
     console.error(`Schedule failed: ${e.message}`);
@@ -1491,6 +1598,10 @@ async function scheduleTagSend(orgId, { opts, tag, templateName, template, heade
     console.log(`  ⚠ PARKED awaiting approval — it will NOT fire until you run:`);
     console.log(`      flowiq bc scheduled approve ${orgId} ${resp.queue_id}`);
   }
+  if (replyRouting) {
+    if (resp.reply_routing?.saved) console.log(`  Replies → ${describeRouting(resp.reply_routing.requested)}  ✓ queued with the send (applied the moment it fires)`);
+    else console.log(`  ⚠ REPLY ROUTING NOT CONFIRMED by the server — cancel and re-schedule, or set it after it fires with: flowiq bc route ${orgId} <broadcast_id> --team … --commit`);
+  }
 }
 
 /** List scheduled broadcasts (queue rows). Read-only. */
@@ -1515,6 +1626,7 @@ export async function scheduledList(orgId, opts = {}) {
     console.log(`    ${fmtSast(s.scheduled_for)} SAST · ${s.status}${flag}`);
     console.log(`    template ${s.template_name ?? "?"} → tag ${s.tag ?? "?"} · ${s.engine} · via ${s.source}${s.scheduled_by ? ` (${s.scheduled_by})` : ""}`);
     if (s.audience_at_schedule != null) console.log(`    ~${s.audience_at_schedule} recipients at schedule time`);
+    if (s.reply_routing) console.log(`    replies → ${describeRouting(s.reply_routing)}`);
     if (s.processed_at) console.log(`    fired ${fmtSast(s.processed_at)} SAST${s.broadcast_id ? ` · broadcastId ${s.broadcast_id}` : ""}`);
     if (s.error_message) console.log(`    error: ${s.error_message}`);
   }
@@ -1628,6 +1740,11 @@ export async function status(orgId, broadcastId, opts = {}) {
   if (b.total_recipients) {
     console.log(`    ${((accepted / b.total_recipients) * 100).toFixed(1)}% of ${b.total_recipients} recipients accepted${d.linked < b.total_recipients ? "  (still sending?)" : ""}`);
   }
+  if (resp.reply_routing) {
+    const rr = resp.reply_routing;
+    console.log(`  replies →   ${describeRouting(rr)}${rr.enabled === false ? "  (switched OFF)" : ""}`);
+    console.log(`              ${rr.routed} chat(s) routed so far${rr.set_by ? ` · set by ${rr.set_by}` : ""}`);
+  }
   if (opts.failures && resp.failures) {
     console.log("");
     console.log(`  Failures by reason:`);
@@ -1641,6 +1758,41 @@ export async function status(orgId, broadcastId, opts = {}) {
   }
 }
 
+/** Show / set / clear reply routing on a broadcast that already exists. Dry run unless --commit. */
+export async function route(orgId, broadcastId, opts = {}) {
+  if (!UUID_RE.test(orgId)) { console.error(`Error: "${orgId}" is not a valid organization UUID.`); process.exit(1); }
+  if (!UUID_RE.test(broadcastId)) { console.error("Error: broadcast id must be a UUID (see `flowiq bc list-remote <org>`)."); process.exit(1); }
+  const parsed = routingFromOpts(opts, { team: "team", member: "member", window: "window", notify: "notify" });
+  if (parsed.error) { console.error(`Error: ${parsed.error}`); process.exit(1); }
+  if (opts.clear && parsed.routing) { console.error("Error: pass --clear OR a --team/--member, not both."); process.exit(1); }
+  let resp;
+  try {
+    resp = await http.post("broadcast", {
+      action: "route", organization_id: orgId, broadcast_id: broadcastId,
+      ...(parsed.routing ? { reply_routing: parsed.routing } : {}),
+      ...(opts.clear ? { clear: true } : {}),
+      commit: !!opts.commit,
+    });
+  } catch (e) { console.error(`Route failed: ${e.body?.error || e.message}`); process.exit(1); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  const b = resp.broadcast;
+  console.log(`Broadcast ${b.id} — ${resp.organization_name}`);
+  console.log(`  template:   ${b.template_name} · sent ${fmtSast(b.created_at)} SAST · ${b.total_recipients ?? "?"} recipient(s)`);
+  console.log(`  replies →   ${resp.current ? describeRouting(resp.current) : "no routing set"}`);
+  console.log(`              ${resp.routed} chat(s) routed so far`);
+  if (resp.mode === "show") {
+    console.log("");
+    console.log(`Set it:   flowiq bc route ${orgId} ${b.id} --team "<team>" [--member <email>] [--window 72h] [--no-notify] --commit`);
+    console.log(`Clear it: flowiq bc route ${orgId} ${b.id} --clear --commit`);
+    return;
+  }
+  console.log("");
+  console.log(`  ${resp.mode === "clear" ? "CLEAR" : "SET"} →     ${resp.mode === "clear" ? "no routing (replies are no longer assigned)" : describeRouting(resp.next)}`);
+  for (const w of resp.warnings || []) console.log(`  ⚠ ${w}`);
+  if (resp.dry_run) { console.log(""); console.log("DRY RUN — nothing changed. Add --commit to apply."); return; }
+  console.log(`  ✓ saved. Only replies that arrive from now on are routed; chats already routed are left as they are.`);
+}
+
 /** Re-send a broadcast to ONLY its failed recipients (transient-failure recovery).
  *  Reconstructs the send from the broadcasts row + re-fires via python. The dry-run
  *  shows the failed count + reason breakdown; --commit creates a NEW broadcast. */

package/src/index.js

@@ -628,6 +628,10 @@ export function run(argv) {
     .option("--python", "with --tag: force the python /meta-broadcast engine (same as the dashboard's Python toggle). NOTE: any tag send >10 recipients ALWAYS uses python automatically")
     .option("--at <when>", "SCHEDULE instead of sending now (tag AND CSV mode, v0.6.1) — \"YYYY-MM-DD HH:MM\" in SAST (e.g. --at \"2026-08-05 09:00\"). CSV: rows are imported+tagged NOW, the python call is queued server-side and shows on the dashboard's Scheduled sends page. Fires automatically; the tag is re-resolved at send time")
     .option("--needs-approval", "with --at: park it awaiting approval (flowiq bc scheduled approve) instead of firing automatically")
+    .option("--route-team <team>", "REPLY ROUTING (v0.7.4): assign every reply to this broadcast to this team (name or id). Once per recipient, typed replies AND button taps, without muting keywords or the AI agent. Forces the python engine")
+    .option("--route-member <who>", "REPLY ROUTING: also/instead assign to this person (email, name or id) — must be an active member of the org")
+    .option("--route-window <dur>", "REPLY ROUTING: how long after the send a reply still counts, e.g. 72h or 3d (default 72h, max 14d)")
+    .option("--no-route-notify", "REPLY ROUTING: assign silently — do not send the team/person their assignment notification")
     .option("--commit", "actually send (omit to dry-run)")
     .option("--yes", "skip the type-the-campaign-name confirm gate (CI)")
     .option("--force-remap", "ignore the saved mapping and rebuild interactively")
@@ -679,6 +683,16 @@ export function run(argv) {
     .option("--limit <n>", "with --failures: how many failed rows to print", "40")
     .option("--json", "raw JSON")
     .action((orgId, broadcastId, opts) => broadcastCmd.status(orgId, broadcastId, opts));
+  broadcast.command("route <organization_id> <broadcast_id>")
+    .description("Reply routing on an EXISTING broadcast: no flags = show it; --team/--member = set it; --clear = switch it off. DRY-RUN unless --commit. Only replies arriving after the change are routed")
+    .option("--team <team>", "assign replies to this team (name or id)")
+    .option("--member <who>", "assign replies to this person (email, name or id)")
+    .option("--window <dur>", "how long after the SEND a reply still counts, e.g. 72h or 3d (default 72h, max 14d)")
+    .option("--no-notify", "assign silently (no assignment notification)")
+    .option("--clear", "remove the routing from this broadcast")
+    .option("--commit", "apply (omit to dry-run)")
+    .option("--json", "raw JSON")
+    .action((orgId, broadcastId, opts) => broadcastCmd.route(orgId, broadcastId, opts));
   broadcast.command("retry <organization_id> <broadcast_id>")
     .description("Re-send a broadcast to ONLY its failed recipients (transient-failure recovery). DRY-RUN by default; --commit re-fires via python")
     .option("--commit", "actually re-send (omit to see the failed count + reasons)")

package/src/reply-routing.test.mjs

@@ -0,0 +1,58 @@
+// Reply routing flag parsing (v0.7.4) — pure functions only, no network.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { parseRouteWindow, routingFromOpts, describeRouting } from "./commands/broadcast.js";
+
+test("window: hours, h suffix, days", () => {
+  assert.deepEqual(parseRouteWindow("72"), { hours: 72 });
+  assert.deepEqual(parseRouteWindow("72h"), { hours: 72 });
+  assert.deepEqual(parseRouteWindow(" 3D "), { hours: 72 });
+  assert.deepEqual(parseRouteWindow("14 days"), { hours: 336 });
+  assert.deepEqual(parseRouteWindow(undefined), { hours: null });
+});
+
+test("window: rejects garbage, zero and anything past 14 days", () => {
+  assert.ok(parseRouteWindow("soon").error);
+  assert.ok(parseRouteWindow("0").error);
+  assert.ok(parseRouteWindow("15d").error);
+  assert.ok(parseRouteWindow("-5").error);
+  assert.ok(parseRouteWindow("1.5h").error);
+});
+
+test("no routing flags = no routing, and the send request stays untouched", () => {
+  assert.deepEqual(routingFromOpts({ routeNotify: true }), { routing: null });
+  assert.deepEqual(routingFromOpts({}), { routing: null });
+});
+
+test("a window or --no-route-notify without a target is an error, never a silent no-op", () => {
+  assert.ok(routingFromOpts({ routeWindow: "48h" }).error);
+  assert.ok(routingFromOpts({ routeNotify: false }).error);
+});
+
+test("team + member + window + silent", () => {
+  assert.deepEqual(
+    routingFromOpts({ routeTeam: " Spa ", routeMember: "kim@example.com", routeWindow: "2d", routeNotify: false }),
+    { routing: { team: "Spa", member: "kim@example.com", window_hours: 48, notify: false } },
+  );
+  // Defaults are left to the server (72 h, notify on) — the client sends only what was typed.
+  assert.deepEqual(routingFromOpts({ routeTeam: "Spa", routeNotify: true }), { routing: { team: "Spa" } });
+});
+
+test("a bad window stops the run", () => {
+  assert.ok(routingFromOpts({ routeTeam: "Spa", routeWindow: "whenever" }).error);
+});
+
+test("`bc route` reads its own flag names", () => {
+  const keys = { team: "team", member: "member", window: "window", notify: "notify" };
+  assert.deepEqual(routingFromOpts({ team: "Spa", window: "24", notify: true }, keys), { routing: { team: "Spa", window_hours: 24 } });
+  assert.deepEqual(routingFromOpts({ notify: true }, keys), { routing: null });
+});
+
+test("describeRouting reads like a sentence", () => {
+  assert.equal(describeRouting(null), "none");
+  assert.equal(
+    describeRouting({ team_name: "Spa", member_name: null, window_hours: 72, notify_team: true, notify_member: null }),
+    "team Spa · first reply within 72 h · team notified",
+  );
+  assert.match(describeRouting({ team_name: "Spa", member_name: "Kim", window_hours: 24, notify_team: false, notify_member: false }), /team Spa \+ Kim .* 24 h .* team not notified, person not notified/);
+});