How to Control Focal Harvest from Your Phone

The Remote Mobile Bot Listener lets you send slash commands to your Focal Harvest instance from anywhere, via Telegram or Discord. You can trigger research sweeps, deep-dive URL scrapes, and status checks — and receive a compact executive summary plus full PDF and Markdown report files directly in your chat, without touching your machine.

This page covers how to create your bots, configure credentials, and use every available command.

Contents

• How It Works
• Set Up a Discord Bot
• Set Up a Telegram Bot
• Configure Focal Harvest
• Start the Listener
• Mobile Command Reference
• Troubleshooting

---

How It Works

The listener runs as a local process on your machine via python main.py → Option 4. It polls for incoming messages using lightweight REST requests — no multi-gigabyte bot frameworks, no background daemon. Every incoming command is checked against a User ID whitelist before execution, so unauthorized users cannot trigger sweeps or consume your API credits.

When a sweep completes, Focal Harvest sends three things to your mobile chat: a compact executive summary text, a .pdf report file, and a .md report file. Both Telegram and Discord channels can be active simultaneously.

---

Set Up a Discord Bot

Create the Application

1. Go to the Discord Developer Portal and sign in.
2. Click New Application, enter a name (e.g. Focal Harvest Bot), and click Create.
3. In the left sidebar, click Bot, then click Reset Token and copy the token string.

Setting key

Save this as discord_bot_token in your config.

Enable Message Content Intent

On the Bot page, scroll to Privileged Gateway Intents and toggle Message Content Intent to ON. Click Save Changes.

caution

Without this toggle enabled, Discord blocks your bot from reading slash commands like /research or /status. This is the most common setup mistake.

Invite the Bot to Your Server

1. In the left sidebar, go to OAuth2 → URL Generator.
2. Under Scopes, check bot.
3. Under Bot Permissions, check Send Messages, Attach Files, and Read Message History.
4. Copy the generated URL, open it in a browser, select your server, and click Authorize.

Get Your Channel ID and User ID

1. In Discord, go to User Settings → Advanced and enable Developer Mode.
2. Right-click the channel where the bot will operate → Copy Channel ID. This is your discord_channel_id.
3. Right-click your own username in chat → Copy User ID. This is your discord_allowed_user_ids entry.

---

Set Up a Telegram Bot

Get a Bot Token from BotFather

1. Open Telegram and search for @BotFather.
2. Send /newbot and follow the prompts to set a name and username (e.g. MyFocalHarvestBot).
3. BotFather replies with an API token (e.g. 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ). Copy it.

Setting key

Save this as telegram_bot_token in your config.

Get Your Telegram User ID

Search for @userinfobot or @raw_data_bot on Telegram, send /start, and the bot replies with your numerical User ID. This value goes in both telegram_chat_id and telegram_allowed_user_ids.

---

Configure Focal Harvest

Option A — Via the TUI (recommended):

python main.py
# Select Option 5: Configure API Keys & Settings

Setting	Key
Setting 8	Telegram Bot Token
Setting 9	Telegram Chat ID
Setting 17	Discord Bot Token
Setting 18	Discord Channel ID
Setting 19	Discord Allowed User IDs (comma-separated)
Setting 20	Telegram Allowed User IDs (comma-separated)

Option B — Directly in config.json:

{
  "telegram_bot_token": "123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ",
  "telegram_chat_id": "123456789",
  "telegram_allowed_user_ids": ["123456789"],
  "discord_bot_token": "your-discord-bot-token",
  "discord_channel_id": "123456789012345678",
  "discord_allowed_user_ids": ["987654321098765432"]
}

---

Start the Listener

python main.py
# Select Option 4: Start Remote Mobile Bot Listener

The terminal confirms both channels are active:

🤖 Remote Bot Listener Active...
• Telegram Status: Online 🟢 (Allowed Users: ['123456789'])
• Discord Status:  Online 🟢 (Allowed Users: ['987654321098765432'])
Listening for incoming slash commands...

The listener keeps running until you stop it with Ctrl+C. Your machine must stay on and connected to the internet for commands to be received.

---

Mobile Command Reference

Command	Example	What It Does
/status	/status	Reports host machine health, active AI provider, proxy status, and local report count
/help	/help	Displays the full command list
/research	/research 'robotics engineering'	Runs a standard web sweep and returns an AI-synthesized report
/research + focus	/research 'robotics' focus on ROS2	Same as above with a custom focus area appended to the synthesis prompt
/deep	/deep 'quantum computing'	Splits the topic into 5 sub-queries and runs a deep parallel sweep
/url (single)	/url 'https://apple.com/newsroom'	Deep-dives a single target URL and synthesizes a report
/url (multi)	/url 'https://site1.com', 'https://site2.com'	Scrapes multiple URLs concurrently and synthesizes a comparative report

tip

Always enclose multi-word topics in single quotes. /research robotics engineering is ambiguous — /research 'robotics engineering' is not.

---

Troubleshooting

HTTP 403 Forbidden on Discord The bot isn't in your server or lacks channel permissions. Re-run the OAuth2 URL Generator and re-invite it, then check the channel's permission settings to confirm the bot role has View Channel, Send Messages, and Read Message History.

Commands arrive in terminal but no reply appears on phone Message Content Intent is off. Go to the Discord Developer Portal → Bot → toggle Message Content Intent to ON → Save Changes.

⚠️ Unauthorized Command in terminal Your User ID isn't in the whitelist. Copy your exact Discord or Telegram User ID and add it under Setting 19 (Discord) or Setting 20 (Telegram) in Option 5.

⚠️ Ambiguous Command Syntax error Your topic contains multiple words without quotes. Use single quotes: /research 'your topic here'.

Now that the listener is running, see Configuration → for how to tune API keys, webhook settings, and pipeline parameters from the same settings menu.