Skip to main content

Bringing a new WhatsApp group online

The onboarding wizard replaces the old eight-step SSH procedure. Total time: about ninety seconds from the moment the customer creates the group to Jarvis replying to their first message.

Prerequisite: the WhatsApp bridge must already be paired (Connectors → WhatsApp, green "Connected" pill). If it's not, run the QR pair from that same page first.

The five steps​

Personas → Onboard new group launches the wizard.

Step 1 — Open the allowlist. The dashboard flips group_policy: open and require_mention: false for the next few minutes. This is what lets the wizard see your new group appearing in the bridge log — otherwise the adapter would filter its messages out. The banner tells you the temporary state so you can restore it if you cancel.

Step 2 — Capture the JID. Ask the customer to send any message in the new group. The wizard tails the bridge log and shows a table of recently seen groups with their JIDs. Click the one you want. This locks it in — future messages in that group will be routed to Claway.

Step 3 — AI-generate the persona. Fill in:

  • Group name — pre-filled from the WhatsApp group's display name.
  • Role brief — one sentence describing what Jarvis should do in this group. "accounting clerk for the Blockway finance team, handles expense logging + invoice review, Cantonese professional tone" is a good shape.
  • Language / Tone — dropdowns for defaults; leave them if the brief is detailed enough.

Click Generate. About five seconds later a full persona lands in the textarea. You can edit it directly or use the AI Assist chips (see the persona guide) before continuing.

Step 4 — Wire scopes. Multi-select which KB collections this group should be allowed to search, and (optionally) which skills. Empty for either one means "none". Leaving KB empty is a valid choice — the group just doesn't get kb_search.

Step 5 — Save and go live. The wizard:

  • Writes channel_prompts.<JID> = generated persona.
  • Adds the JID to group_allow_from.
  • Restores the allowlist policy back to closed if the customer wants scope-controlled access.
  • Writes kb_scope.<JID>.allow and (if needed) auto-adds kb_search to platform_toolsets.whatsapp.
  • Ends any lingering session for that JID so the next message starts fresh.

Close the dialog. Ask the customer to send a real message. Jarvis should reply within a few seconds. If not, see below.

Recovery — what if you closed the dialog by mistake​

If you close the wizard without finishing, the allowlist policy is restored to its previous state via beforeunload / sendBeacon. The half- finished persona is discarded. Nothing on disk is stranded.

If the browser tab crashes mid-wizard, the same beacon fires from the browser's page-hide event; if that also fails, the allowlist may be left open. Check Connectors → WhatsApp → Manage and revert group_policy manually.

What goes wrong most often​

  • No groups appear in step 2. The bridge is paired but the group's messages aren't reaching the adapter — usually because the bot account hasn't actually been added to the group yet. Confirm on the customer's phone.
  • Generated persona doesn't match the role. The role brief was too short. Cancel, restart, write a longer brief. Two or three sentences is the sweet spot.
  • Jarvis replies but ignores the KB. The KB-first rule was not included. Open the persona editor, use the Add KB-first rule preset.
  • Jarvis doesn't reply at all. Check Live Events for the inbound message — if it's not there, the JID capture missed the right group. Re-run the wizard.

After the wizard: the twelve-hour check​

The most common productionization failure is a persona rule that reads well but backfires in practice. Twelve hours after onboarding, open Conversations and skim the first day of transcripts. Look for:

  • Cases where Jarvis called kb_search and got nothing but the answer was in your KB anyway — that's a chunking problem, re-ingest the doc as multiple smaller files.
  • Cases where Jarvis answered from training data instead of KB — that's a persona rule problem, tighten the KB-first rule.
  • Tone drift — Jarvis being too formal / too casual. Use the AI Edit mode with a one-line correction.

Small corrections in week one save large re-writes in month two.