mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-04-25 00:51:20 +00:00
docs: enhance WhatsApp setup instructions and introduce mode selection
Updated the README and messaging documentation to clarify the two modes for WhatsApp integration: 'bot' mode (recommended) and 'self-chat' mode. Improved setup instructions to guide users through the configuration process, including allowlist management and dependency installation. Adjusted CLI commands to reflect these changes and ensure a smoother user experience. Additionally, modified the WhatsApp bridge to support the new mode functionality.
This commit is contained in:
teknium1
parent
221e4228ec
commit
14b0ad95c6
6 changed files with 148 additions and 55 deletions
|
|
@ -168,7 +168,7 @@ def cmd_gateway(args):
|
|||
|
||||
|
||||
def cmd_whatsapp(args):
|
||||
"""Set up WhatsApp: enable, configure allowed users, install bridge, pair via QR."""
|
||||
"""Set up WhatsApp: choose mode, configure, install bridge, pair via QR."""
|
||||
import os
|
||||
import subprocess
|
||||
from pathlib import Path
|
||||
|
|
@ -177,12 +177,55 @@ def cmd_whatsapp(args):
|
|||
print()
|
||||
print("⚕ WhatsApp Setup")
|
||||
print("=" * 50)
|
||||
print()
|
||||
print("This will link your WhatsApp account to Hermes Agent.")
|
||||
print("The agent will respond to messages sent to your WhatsApp number.")
|
||||
print()
|
||||
|
||||
# Step 1: Enable WhatsApp
|
||||
# ── Step 1: Choose mode ──────────────────────────────────────────────
|
||||
current_mode = get_env_value("WHATSAPP_MODE") or ""
|
||||
if not current_mode:
|
||||
print()
|
||||
print("How will you use WhatsApp with Hermes?")
|
||||
print()
|
||||
print(" 1. Separate bot number (recommended)")
|
||||
print(" People message the bot's number directly — cleanest experience.")
|
||||
print(" Requires a second phone number with WhatsApp installed on a device.")
|
||||
print()
|
||||
print(" 2. Personal number (self-chat)")
|
||||
print(" You message yourself to talk to the agent.")
|
||||
print(" Quick to set up, but the UX is less intuitive.")
|
||||
print()
|
||||
try:
|
||||
choice = input(" Choose [1/2]: ").strip()
|
||||
except (EOFError, KeyboardInterrupt):
|
||||
print("\nSetup cancelled.")
|
||||
return
|
||||
|
||||
if choice == "1":
|
||||
save_env_value("WHATSAPP_MODE", "bot")
|
||||
wa_mode = "bot"
|
||||
print(" ✓ Mode: separate bot number")
|
||||
print()
|
||||
print(" ┌─────────────────────────────────────────────────┐")
|
||||
print(" │ Getting a second number for the bot: │")
|
||||
print(" │ │")
|
||||
print(" │ Easiest: Install WhatsApp Business (free app) │")
|
||||
print(" │ on your phone with a second number: │")
|
||||
print(" │ • Dual-SIM: use your 2nd SIM slot │")
|
||||
print(" │ • Google Voice: free US number (voice.google) │")
|
||||
print(" │ • Prepaid SIM: $3-10, verify once │")
|
||||
print(" │ │")
|
||||
print(" │ WhatsApp Business runs alongside your personal │")
|
||||
print(" │ WhatsApp — no second phone needed. │")
|
||||
print(" └─────────────────────────────────────────────────┘")
|
||||
else:
|
||||
save_env_value("WHATSAPP_MODE", "self-chat")
|
||||
wa_mode = "self-chat"
|
||||
print(" ✓ Mode: personal number (self-chat)")
|
||||
else:
|
||||
wa_mode = current_mode
|
||||
mode_label = "separate bot number" if wa_mode == "bot" else "personal number (self-chat)"
|
||||
print(f"\n✓ Mode: {mode_label}")
|
||||
|
||||
# ── Step 2: Enable WhatsApp ──────────────────────────────────────────
|
||||
print()
|
||||
current = get_env_value("WHATSAPP_ENABLED")
|
||||
if current and current.lower() == "true":
|
||||
print("✓ WhatsApp is already enabled")
|
||||
|
|
@ -190,26 +233,36 @@ def cmd_whatsapp(args):
|
|||
save_env_value("WHATSAPP_ENABLED", "true")
|
||||
print("✓ WhatsApp enabled")
|
||||
|
||||
# Step 2: Allowed users
|
||||
# ── Step 3: Allowed users ────────────────────────────────────────────
|
||||
current_users = get_env_value("WHATSAPP_ALLOWED_USERS") or ""
|
||||
if current_users:
|
||||
print(f"✓ Allowed users: {current_users}")
|
||||
response = input("\n Update allowed users? [y/N] ").strip()
|
||||
try:
|
||||
response = input("\n Update allowed users? [y/N] ").strip()
|
||||
except (EOFError, KeyboardInterrupt):
|
||||
response = "n"
|
||||
if response.lower() in ("y", "yes"):
|
||||
phone = input(" Phone number(s) (e.g. 15551234567, comma-separated): ").strip()
|
||||
if wa_mode == "bot":
|
||||
phone = input(" Phone numbers that can message the bot (comma-separated): ").strip()
|
||||
else:
|
||||
phone = input(" Your phone number (e.g. 15551234567): ").strip()
|
||||
if phone:
|
||||
save_env_value("WHATSAPP_ALLOWED_USERS", phone.replace(" ", ""))
|
||||
print(f" ✓ Updated to: {phone}")
|
||||
else:
|
||||
print()
|
||||
phone = input(" Your phone number (e.g. 15551234567): ").strip()
|
||||
if wa_mode == "bot":
|
||||
print(" Who should be allowed to message the bot?")
|
||||
phone = input(" Phone numbers (comma-separated, or * for anyone): ").strip()
|
||||
else:
|
||||
phone = input(" Your phone number (e.g. 15551234567): ").strip()
|
||||
if phone:
|
||||
save_env_value("WHATSAPP_ALLOWED_USERS", phone.replace(" ", ""))
|
||||
print(f" ✓ Allowed users set: {phone}")
|
||||
else:
|
||||
print(" ⚠ No allowlist — the agent will respond to ALL incoming messages")
|
||||
|
||||
# Step 3: Install bridge deps
|
||||
# ── Step 4: Install bridge dependencies ──────────────────────────────
|
||||
project_root = Path(__file__).resolve().parents[1]
|
||||
bridge_dir = project_root / "scripts" / "whatsapp-bridge"
|
||||
bridge_script = bridge_dir / "bridge.js"
|
||||
|
|
@ -234,13 +287,16 @@ def cmd_whatsapp(args):
|
|||
else:
|
||||
print("✓ Bridge dependencies already installed")
|
||||
|
||||
# Step 4: Check for existing session
|
||||
# ── Step 5: Check for existing session ───────────────────────────────
|
||||
session_dir = Path.home() / ".hermes" / "whatsapp" / "session"
|
||||
session_dir.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
if (session_dir / "creds.json").exists():
|
||||
print("✓ Existing WhatsApp session found")
|
||||
response = input("\n Re-pair? This will clear the existing session. [y/N] ").strip()
|
||||
try:
|
||||
response = input("\n Re-pair? This will clear the existing session. [y/N] ").strip()
|
||||
except (EOFError, KeyboardInterrupt):
|
||||
response = "n"
|
||||
if response.lower() in ("y", "yes"):
|
||||
import shutil
|
||||
shutil.rmtree(session_dir, ignore_errors=True)
|
||||
|
|
@ -251,11 +307,16 @@ def cmd_whatsapp(args):
|
|||
print(" Start the gateway with: hermes gateway")
|
||||
return
|
||||
|
||||
# Step 5: Run bridge in pair-only mode (no HTTP server, exits after QR scan)
|
||||
# ── Step 6: QR code pairing ──────────────────────────────────────────
|
||||
print()
|
||||
print("─" * 50)
|
||||
print("📱 Scan the QR code with your phone:")
|
||||
print(" WhatsApp → Settings → Linked Devices → Link a Device")
|
||||
if wa_mode == "bot":
|
||||
print("📱 Open WhatsApp (or WhatsApp Business) on the")
|
||||
print(" phone with the BOT's number, then scan:")
|
||||
else:
|
||||
print("📱 Open WhatsApp on your phone, then scan:")
|
||||
print()
|
||||
print(" Settings → Linked Devices → Link a Device")
|
||||
print("─" * 50)
|
||||
print()
|
||||
|
||||
|
|
@ -267,12 +328,28 @@ def cmd_whatsapp(args):
|
|||
except KeyboardInterrupt:
|
||||
pass
|
||||
|
||||
# ── Step 7: Post-pairing ─────────────────────────────────────────────
|
||||
print()
|
||||
if (session_dir / "creds.json").exists():
|
||||
print("✓ WhatsApp paired successfully!")
|
||||
print()
|
||||
print("Start the gateway with: hermes gateway")
|
||||
print("Or install as a service: hermes gateway install")
|
||||
if wa_mode == "bot":
|
||||
print(" Next steps:")
|
||||
print(" 1. Start the gateway: hermes gateway")
|
||||
print(" 2. Send a message to the bot's WhatsApp number")
|
||||
print(" 3. The agent will reply automatically")
|
||||
print()
|
||||
print(" Tip: Agent responses are prefixed with '⚕ Hermes Agent'")
|
||||
else:
|
||||
print(" Next steps:")
|
||||
print(" 1. Start the gateway: hermes gateway")
|
||||
print(" 2. Open WhatsApp → Message Yourself")
|
||||
print(" 3. Type a message — the agent will reply")
|
||||
print()
|
||||
print(" Tip: Agent responses are prefixed with '⚕ Hermes Agent'")
|
||||
print(" so you can tell them apart from your own messages.")
|
||||
print()
|
||||
print(" Or install as a service: hermes gateway install")
|
||||
else:
|
||||
print("⚠ Pairing may not have completed. Run 'hermes whatsapp' to try again.")
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue