Google Contacts Scraper

Install Hermes Agent on macOS or Windows, connect a Telegram bot, add a Google Maps contact scraper command, keep target-based scraping jobs running, and connect a real phone number through AgentPhone. Scope This guide is for a Hermes agent that receives Telegram commands such as /gmaps dentists in Mumbai 50, starts a Google Maps scraping job, sends progress back to Telegram, and saves the

final contacts as a CSV file.

Primary command /gmaps <business or place search> <target> Status command /gmaps_status Output folder ~/.hermes/scrapgoal/google-maps/<job-id>/results.csv

Scraper source zohaibbashir/Google-Maps-Scrapper, wrapped by a Hermes plugin

Architecture

1. Hermes Agent runs locally or on a server and owns the model provider, memory, tools, and plugin

system.

1. The Hermes gateway connects Telegram to the agent and listens for messages or slash

commands.

1. The google_maps_scraper plugin intercepts /gmaps before the normal LLM response path.
2. The plugin starts a Python runner that calls the upstream Playwright scraper in repeated rounds.
3. The runner merges unique rows, writes results.csv, and stops when the target is reached or

no more usable results are found.

1. Telegram receives start, progress, completion, and final contact messages.

Compliance note. Google Maps data extraction can trigger rate limits or blocks. Use small batches, avoid aggressive parallel scraping, and follow the terms and legal requirements that apply to your use case.

1. Install Hermes Agent on macOS

Use the Hermes Desktop installer when you want the desktop app and CLI together. For a command- line installation, use the official shell installer.

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.zshrc # or: source ~/.bashrc
hermes doctor
hermes

Choose and verify a model provider before adding Telegram. The provider must have enough context for tool-using workflows.

hermes model
hermes setup # optional full setup wizard
hermes setup --portal # optional Nous Portal path

1. Install Hermes Agent on Windows

On Windows, run PowerShell as the user who will run the bot. The native installer sets up the command-line environment.

iex (irm https://hermes-agent.nousresearch.com/install.ps1)
hermes doctor
hermes model
hermes

If the hermes command is not found after installation, open a fresh PowerShell window and check that the Hermes bin directory is on PATH.

1. Connect Telegram to Hermes
2. Open Telegram and message @BotFather.
3. Send /newbot, choose a display name, then choose a username that ends in bot.
4. Copy the bot token. Store it only in Hermes configuration or a password manager.
5. Get your numeric Telegram user ID from @userinfobot or @get_id_bot.
6. Run the Hermes gateway setup and choose Telegram.

hermes gateway setup
hermes gateway

For group chats, Telegram privacy mode matters. With privacy mode on, a bot mainly sees slash commands, replies to its own messages, and service events. Disable privacy mode in BotFather or promote the bot as a group admin if the bot must read normal group messages.

/mybots

Bot Settings

Group Privacy

Turn off

1. Install the Google Maps Scraper Engine

The upstream scraper uses Python and Playwright. Its README recommends Python 3.8 or 3.9 because newer Python versions may have dependency issues.

macOS

mkdir -p ~/.hermes/google-maps-scrapper
git clone https://github.com/zohaibbashir/Google-Maps-Scrapper.git \
~/.hermes/google-maps-scrapper/source
cd ~/.hermes/google-maps-scrapper/source

python3.9 -m venv ../venv ../venv/bin/python -m pip install –upgrade pip ../venv/bin/pip install -r requirements.txt ../venv/bin/playwright install chromium

Windows PowerShell

mkdir $env:USERPROFILE\.hermes\google-maps-scrapper
git clone https://github.com/zohaibbashir/Google-Maps-Scrapper.git `

$env:USERPROFILE\.hermes\google-maps-scrapper\source

cd $env:USERPROFILE\.hermes\google-maps-scrapper\source
py -3.9 -m venv ..\venv

..\venv\Scripts\python -m pip install –upgrade pip ..\venv\Scripts\pip install -r requirements.txt ..\venv\Scripts\playwright install chromium Run a direct smoke test before wiring Telegram.

python main.py -s "dentists in Mumbai" -t 3 -o test-results.csv

1. Add the Hermes Scraper Plugin

The upstream scraper alone is not enough for Telegram. Add a Hermes plugin that registers the slash commands, starts the runner, tracks job state, and sends progress messages. Plugin folder ~/.hermes/plugins/google_maps_scraper/ Manifest plugin.yaml with name google_maps_scraper Gateway hook __init__.py registers /gmaps, /google_maps_scraper, and

/gmaps_status

Runner runner.py calls the upstream scraper and merges output rows until the target is reached Enable the plugin in the profile that runs your Telegram bot.

# ~/.hermes/profiles/<profile-name>/config.yaml

plugins

enabled

• google_maps_scraper

disabled: [] Use profile-specific paths when you run multiple Hermes agents on one machine. For example, a bot profile named agent7 should enable the plugin in ~/.hermes/profiles/agent7/config.yaml and run the gateway with that profile.

hermes --profile agent7 gateway run --replace

1. Configure Target-Based Scraping

The runner should request more listings than are still needed, merge unique contacts, and write only the first target count to the final CSV. A job that asks for 50 contacts should continue through scraping rounds until it reaches 50 or the available results are exhausted.

Behavior Recommended setting

Maximum contacts per Telegram

job Start with 50 to 100. Cap very large requests to reduce blocking risk. Retry rounds Use multiple rounds with increasing requested totals. No-growth handling Stop after repeated rounds that add no new unique rows. Phone-only mode Support –require-phone or –phone-only. State file Write job.json beside results.csv.

/gmaps dentists in Mumbai 50
/gmaps restaurants in Chennai 50 --require-phone
/google_maps_scraper interior designers in Coimbatore --limit 25
/gmaps_status

1. Keep the Gateway Running

The Telegram bot only responds while the Hermes gateway for that profile is running. Use a service manager so the gateway starts after login or boot.

macOS LaunchAgent

mkdir -p ~/Library/LaunchAgents
plutil -lint ~/Library/LaunchAgents/ai.hermes.gateway-agent7.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.hermes.gateway-

agent7.plist

launchctl kickstart -k gui/$(id -u)/ai.hermes.gateway-agent7
launchctl list | grep ai.hermes.gateway-agent7

The plist should run the Hermes virtual environment Python with arguments like this: <string>/Users/<user>/.hermes/hermes-agent/venv/bin/python</string> <string>-m</string> <string>hermes_cli.main</string> <string>–profile</string> <string>agent7</string> <string>gateway</string> <string>run</string> <string>–replace</string>

Windows Task Scheduler

1. Open Task Scheduler and create a task named Hermes Gateway agent7.
2. Set trigger to logon or startup.
3. Set action to start powershell.exe.
4. Use arguments that run the profile gateway.

-NoProfile -ExecutionPolicy Bypass -Command "hermes –profile agent7 gateway run — replace"

1. Test End to End
2. Run hermes doctor and fix any provider or environment issue.
3. Run hermes –profile agent7 gateway status or inspect gateway logs.
4. Open Telegram and send hello. Confirm the bot replies.
5. Send /help. Confirm the command menu appears.
6. Send /gmaps_status. Confirm the scraper plugin responds.
7. Send a small job, for example /gmaps dentists in Mumbai 4.
8. Confirm Telegram receives a start message, progress updates, and final contact rows.
9. Confirm results.csv exists under the job folder.

tail -f ~/.hermes/profiles/agent7/logs/gateway.log
ls ~/.hermes/scrapgoal/google-maps/
cat ~/.hermes/scrapgoal/google-maps/<job-id>/job.json

1. Connect a Phone Number with AgentPhone

AgentPhone adds real phone network capability to Hermes: buy numbers, make outbound AI calls, receive inbound calls, manage SMS, and access call transcripts. The simplest path is the AgentPhone MCP server.

1. Create or log in to AgentPhone and get an API key from the settings page.
2. Add the AgentPhone MCP server to the Hermes profile configuration.
3. Restart Hermes so it loads the MCP tools.
4. Ask Hermes to buy a number, create a voice agent, place a call, or summarize recent calls.

# ~/.hermes/profiles/agent7/config.yaml

mcp

servers

agentphone

command: npx args: ["-y", "agentphone-mcp"]

env

AGENTPHONE_API_KEY: your_api_key_here

For inbound calls controlled by Hermes, enable the Hermes API server and expose it through a secure public URL or tunnel. Keep the API key private and use HTTPS in production.

# ~/.hermes/profiles/agent7/.env
API_SERVER_ENABLED=true
API_SERVER_PORT=8642
API_SERVER_KEY=replace-with-a-strong-secret
hermes --profile agent7 gateway

ngrok http 8642 Then configure AgentPhone to send webhook events to your public webhook route. The webhook handler converts the caller transcript into a Hermes chat request and returns Hermes' response for speech playback.

Operational Checklist

Never paste Telegram bot tokens, model provider keys, or AgentPhone keys into chat logs or screenshots. Use one Telegram bot token per Hermes profile when running multiple agents. Give each profile separate logs, output folders, API server ports, and launch/service names. Start with small scraper targets before running larger lead batches. Keep the scraper visible or headless according to your operating environment. Back up important CSV outputs from ~/.hermes/scrapgoal/google-maps/. Run hermes update only after saving known-good config and plugin files.

Troubleshooting

Symptom Check

Telegram bot does not answer Confirm the correct profile gateway is running, token is valid, and user ID is authorized. Slash command is unknown Confirm google_maps_scraper is enabled in the active profile and the gateway was restarted. Scraper starts but saves no rows Run the upstream scraper directly, reduce target size, and check Google blocking or DOM changes.

Playwright error Run playwright install chromium inside the scraper virtual

environment.

AgentPhone tools

missing Confirm Node.js is available, the MCP config is in the active profile, and AGENTPHONE_API_KEY is set. Sources

Hermes Agent installation and quickstart: https://hermes-agent.nousresearch.com/docs/getting-

started/installation

Hermes Agent Telegram setup: https://github.com/NousResearch/hermes-

agent/blob/main/website/docs/user-guide/messaging/telegram.md

Hermes Agent API server: https://hermes-agent.nousresearch.com/docs/user-guide/features/api-

server

Google Maps Scrapper repository: https://github.com/zohaibbashir/Google-Maps-Scrapper

AgentPhone Hermes integration: https://docs.agentphone.ai/integrations/connect-your-ai/hermes- agent