[Feature]: `hermes whatsapp setup` — Interactive one-command WhatsApp configuration wizard

[webtecnica]

Problem

Setting up WhatsApp on Hermes Agent is significantly more complex and error-prone than other platforms — especially Telegram, which has a straightforward hermes gateway setup flow that just asks for a bot token and works.

WhatsApp requires at least 4 manual configuration steps that a new user cannot reasonably discover on their own:

1. Pairing — hermes whatsapp → scan QR. This works (more or less).
2. Allowlist — Set WHATSAPP_ALLOWED_USERS to the owner's personal phone number, NOT the bot's number. This distinction is not documented or obvious. First-time users routinely set it to the bot's own number, locking themselves out.
3. DM policy — Change dm_policy from "open" to "allowlist" in config.yaml, otherwise the gateway refuses to start when WHATSAPP_ALLOW_ALL_USERS=false.
4. Home channel — Set WHATSAPP_HOME_CHANNEL in .env for cron delivery. Without this, cron job output never reaches the user on WhatsApp.

On top of that:

• The gateway service must be restarted via hermes-gateway.service (not hermes-dashboard), which is easy to confuse.
• The delivery format for cron targets is unintuitive: whatsapp:<LID>@lid (not the phone JID format <number>@s.whatsapp.net).
• There is no built-in test to verify delivery works after setup.

This matters because WhatsApp is the dominant messaging platform in many countries — Brazil, India, Mexico, much of Europe, Southeast Asia, and Africa. For users in these regions, WhatsApp is not a "nice to have" integration; it's the primary way they interact with messaging services. A painful WhatsApp setup creates a disproportionate onboarding barrier for a huge portion of the global user base.

Proposed Solution: hermes whatsapp setup Interactive Wizard

A single guided command that configures everything in one pass:

$ hermes whatsapp setup
┌─ WhatsApp Setup ──────────────────────────────────┐
│                                                    │
│  This will guide you through WhatsApp setup.       │
│  You'll need your WhatsApp account ready to scan   │
│  a QR code.                                        │
│                                                    │
├────────────────────────────────────────────────────┤
│                                                    │
│  Step 1/4: Pairing                                  │
│  ─────────────────                                  │
│  Starting WhatsApp bridge...                        │
│                                                    │
│  📱 Scan this QR code with WhatsApp:               │
│  ┌─────────────────────────────────────────┐       │
│  │           ██████████████████            │       │
│  │           ██  QR CODE  ██               │       │
│  │           ██████████████████            │       │
│  └─────────────────────────────────────────┘       │
│                                                    │
│  ✓ Paired successfully as: 5511999999999           │
│                                                    │
├────────────────────────────────────────────────────┤
│                                                    │
│  Step 2/4: Who can use this bot?                    │
│  ───────────────────────────────                    │
│                                                    │
│  We detected your paired account: 5511999999999     │
│                                                    │
│  Is this YOUR personal number? [Y/n]                │
│  → Y                                               │
│                                                    │
│  ✓ WHATSAPP_ALLOWED_USERS = 5511999999999           │
│  ✓ WHATSAPP_ALLOW_ALL_USERS = false                 │
│  ✓ dm_policy = allowlist                           │
│                                                    │
├────────────────────────────────────────────────────┤
│                                                    │
│  Step 3/4: Cron delivery home channel               │
│  ─────────────────────────────────────              │
│                                                    │
│  Should cron job output be delivered here? [Y/n]    │
│  → Y                                               │
│                                                    │
│  ✓ WHATSAPP_HOME_CHANNEL = <your_chat_id>           │
│                                                    │
├────────────────────────────────────────────────────┤
│                                                    │
│  Step 4/4: Test delivery                            │
│  ───────────────────────                            │
│                                                    │
│  Sending test message...                            │
│  ✓ Test message delivered to your WhatsApp!        │
│                                                    │
├────────────────────────────────────────────────────┤
│                                                    │
│  ✅ WhatsApp fully configured!                      │
│                                                    │
│  Summary:                                           │
│  ─────────────────────────────────────────────      │
│  Paired as:       5511999999999                     │
│  Allowed users:    5511999999999 (only you)         │
│  DM policy:        allowlist (no randoms)           │
│  Groups:           blocked                          │
│  Home channel:     ✓ (cron deliveries enabled)      │
│  Test delivery:    ✓                                │
│                                                    │
└────────────────────────────────────────────────────┘

Under the hood, the wizard would:

1. Pair (reuse existing hermes whatsapp flow)
2. Detect owner — After pairing, read creds.json's me.id to know the bot's own number. Ask the user if this is their personal number, or let them type a different one.
3. Set allowlist — Write WHATSAPP_ALLOWED_USERS=<owner_number> and WHATSAPP_ALLOW_ALL_USERS=false to .env.
4. Set dm_policy — Run hermes config set whatsapp.dm_policy allowlist (handles the config.yaml restriction the agent has).
5. Set home channel — Detect the user's chat LID from the lid-mapping files and write WHATSAPP_HOME_CHANNEL=<LID>@lid to .env.
6. Test delivery — Send a test message via the bridge to confirm everything works.
7. Restart gateway — Prompt to restart hermes-gateway.service.
8. Print summary — Clear overview of what was configured.

Benefits

• Parity with Telegram setup — Telegram's hermes gateway setup asks for a token and works. WhatsApp should be equally straightforward.
• Eliminates the "wrong number" trap — The Terminal tool #1 mistake (setting the bot's number instead of the owner's) is caught automatically.
• No manual .env editing — All three env vars (ALLOWED_USERS, ALLOW_ALL_USERS, HOME_CHANNEL) plus dm_policy in config.yaml are set by the wizard.
• Works out of the box — New users in WhatsApp-dominant countries (Brazil, India, Mexico, etc.) can be productive in minutes, not hours.
• Self-verifying — The test step catches silent failures immediately.

Implementation Considerations

• The hermes_cli/main.py already has a whatsapp_setup function (around line 2506) that handles allowlist configuration — this could be extended.
• The gateway already exposes _standalone_send for WhatsApp — the test step can reuse this.
• No new dependencies needed — everything uses existing infrastructure (qrcode for pairing, the bridge for sending, hermes config for YAML edits).
• The wizard should be idempotent — re-running it should update the config, not error out.

Related

• This complements PR feat(whatsapp): QR pairing panel in dashboard #46698 ("feat(whatsapp): QR pairing panel in dashboard") by improving the CLI setup flow.
• Issue [Feature]: QR code color-inversion detection for dark-mode terminals (WhatsApp pairing) #58038 ("QR code color-inversion detection for dark-mode terminals") would improve the QR scanning step in dark terminals.
• The existing hermes_cli/gateway.py has print_qr_code() and pairing infrastructure that this can build on.

[webtecnica]

🚨 Real-world impact: bot responding to random contacts

Another critical point that should be addressed by this wizard: when WhatsApp is first enabled with default settings (dm_policy: open, WHATSAPP_ALLOW_ALL_USERS=true), the bot immediately starts responding to ANY contact who messages the number — without warning.

This happened to me when I first set up WhatsApp. The Hermes agent gave no prompts or warnings about access control. Within minutes, the bot was responding to random contacts from my address book — colleagues, family members, clients — who had messaged me earlier. It was invasive and could have been professionally damaging if the bot had said something inappropriate.

The fix required manual intervention: I had to ask Hermes to pause and figure out how to restrict it. The configuration involved multiple steps (allowlist, dm_policy, allow_all_users) that weren't obvious.

This is arguably the #1 reason this wizard is necessary. A new user should never experience their bot DM-ing their grandmother or boss unprompted. The wizard should:

1. Warn explicitly when allowing open access: "⚠️ With this setting, ANYONE who messages this number will get a response from the bot."
2. Default to restricted access — the wizard should default to "only me" mode and require explicit opt-in for open access.
3. Explain what "open" means — many users don't realize dm_policy: open means the bot talks to everyone.

This is especially important for WhatsApp because unlike Telegram (where you create a bot-specific account with a @username), WhatsApp uses your personal phone number. The stakes are higher — it's not a separate bot identity that can be thrown away; it's your actual contact number with your real contacts.

[webtecnica]

Implemented in PR #58553 — hermes whatsapp setup one-command guided wizard.

5 steps: pairing → allowlist + dm_policy → home channel → test delivery → gateway restart.

[GottZ]

This was generated by AI during triage.

Summary

One PR addresses issue #58041. #58553 adds the requested five-step WhatsApp setup wizard covering pairing, access restrictions, cron home-channel configuration, delivery testing, and gateway restart, but its implementation does not yet reliably complete the reported setup path.

Related pull requests

• feat(whatsapp): hermes whatsapp setup — one-command guided setup wizard #58553 partial — (+868/-3) — partial fix: Adds the full guided workflow, but the diff invokes a nonexistent python -m hermes_cli entry point while ignoring its return code, never selects or saves WHATSAPP_MODE, and tests delivery before restarting even though pair-only mode exposes no HTTP server. Consistent with the visible keep_open review on feat(whatsapp): hermes whatsapp setup — one-command guided setup wizard #58553, these defects leave DM-policy persistence, non-self inbound handling, and fresh-setup delivery verification unresolved.

Suggested consolidation

Keep #58553 as the sole consolidation target, but do not merge it yet; amend it to use a verified config writer, configure WHATSAPP_MODE, and start or restart the bridge before testing delivery. There are no duplicate PRs to close.

Complex graph

flowchart LR
    classDef open fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
    classDef merged fill:#dcfce7,stroke:#15803d,color:#14532d
    classDef closed fill:#e5e7eb,stroke:#6b7280,color:#1f2937
    classDef unverified fill:#f3f4f6,stroke:#9ca3af,color:#374151
    classDef best stroke-width:3px,stroke:#b45309
    classDef target stroke-width:3px,stroke:#4338ca
    I58041(["issue #58041 (open)"])
    P58553["PR #58553 (open)"]
    P58553 -.->|partial| I58041
    class I58041 open
    class I58041 target
    class P58553 open
    click I58041 "https://github.com/NousResearch/hermes-agent/issues/58041"
    click P58553 "https://github.com/NousResearch/hermes-agent/pull/58553"

Loading

Graph: solid arrow = fixes / best fix, dashed arrow = partial or unverified (see edge label); boxed group = PRs duplicating each other; amber border = best fix; indigo border = target; gray node = closed or no verify verdict yet (state tag in the node label).

Cross-PR triage: Reviewed 1 pull request and 1 issue in this complex. Each diff was read against this issue; Assessment working set: 32 kB of PR diffs, 11 kB of issue/PR text, 4 kB of discussion (7 comments), 1 verify verdict. verdicts reflect diff content, not PR titles. Part of an automated triage batch.