agentos.guide › blog

Hermes Agent WhatsApp: Connect One Route, Then Paste Five Prompts That Turn Your Phone Into The Front Door Of Your Agent OS

By Julian Goldie · 11 November 2026 · agentos.guide

Hermes Agent WhatsApp turns your Agent OS into something you can run from your phone: voice-note a task, forward a document, and get the answer back in the same chat.

This guide gets one route connected, then hands you five prompts that make the agent useful there without letting it message anyone it shouldn't.

Both routes are covered: the unofficial Baileys bridge and Meta's official Cloud API.

If you want my team to help map the wider plan, book a free SEO strategy session.

Quick Start: Choose A Route, Then Run One Command

The bridge guide needs Node.js v20+, npm and a phone to scan a QR code under Settings, Linked Devices.

The Cloud API guide asks for three things up front: a business account with Meta, its own phone number, and a webhook Meta can reach over HTTPS (Cloudflare Tunnel is the suggested way to expose it).

Either way, finish with the gateway as a service so it survives a reboot:

hermes gateway install

Set The Allowlist Before You Paste A Single Prompt

# ~/.hermes/.env  (bridge)
WHATSAPP_ALLOWED_USERS=447700900123

# ~/.hermes/.env  (Cloud API)
WHATSAPP_CLOUD_ALLOWED_USERS=447700900123

Country code first, no plus sign, commas between numbers.

Without an allowlist the gateway turns everyone away, which the messaging overview describes as the safe default for a bot with terminal access.

On a private bridge number, add whatsapp.unauthorized_dm_behavior: ignore to config.yaml so strangers get no reply at all.

Put the bridge on a spare number rather than your own, since WhatsApp can restrict accounts that run unofficial bots.

🔥 Want the Agent OS with WhatsApp already set up?

Inside the AI Profit Boardroom you get the installable Agent OS, step-by-step video trainings, four coaching calls a week and 3,400+ members sharing their gateway configs.

→ Join the AI Profit Boardroom

Prompt 1: The Channel Rules

Paste this into the WhatsApp chat first, so the agent saves your house rules to memory.

Remember these rules for every WhatsApp conversation:
1. Keep replies short enough to read on a phone. Bullet points, no tables.
2. You may reply to me and to allowlisted staff only.
3. Never message a customer, supplier or any other number yourself.
   If something needs to go out, write it as a draft and label it DRAFT.
4. Before running anything that deletes, pays, posts or emails,
   stop and ask me first.
Confirm by listing the four rules back to me.

Ask it to repeat the rules whenever you change them, so you know the memory holds the current version.

Rule three matters most, because the bridge docs say not to automate outbound messages to anyone who hasn't messaged first.

Prompt 2: Voice Note To Job Log

Both routes transcribe incoming voice notes with your speech-to-text provider, so this works from a van, a shop floor or a car park.

When I send a voice note that starts with "job", treat it as a job record.
Append one line to ~/business/jobs.csv with: date, customer name,
address, work done, parts used, follow-up needed (yes/no).
Reply with the line you added so I can check it.
If anything is unclear, ask me one question instead of guessing.

A plumber or electrician can run the whole working day like this and tidy the sheet on Friday.

The "ask one question" line stops the agent inventing a postcode when the van was noisy.

If you prefer typing, the same trigger word works on a text message.

Prompt 3: Forwarded Document Triage

When I forward a document or photo of a receipt, invoice or quote:
- Tell me what it is, who it is from, the date and the total.
- Save it to ~/business/inbox/ with a clear filename.
- Flag anything due within seven days.
Do not pay, accept or reply to anything. Report only.

On the Cloud API, small text files up to 100KB are read straight into the conversation and larger ones are cached for the agent's tools, per the docs.

An accountant's assistant can forward a batch of receipts and get a clean list back.

Quoting an earlier photo and asking "what is this?" also works on both routes, because quoting a file attaches it to the new turn.

The "report only" line keeps the agent from replying to the sender on your behalf.

Prompt 4: The Team Group Assistant (Bridge Only)

Groups are bridge-only, because the Cloud API adapter handles direct messages only in v1.

First admit just that group and require a mention:

WHATSAPP_GROUP_POLICY=allowlist
WHATSAPP_GROUP_ALLOWED_USERS=120363001234567890@g.us
WHATSAPP_REQUIRE_MENTION=true

Then give the agent its group brief:

In the staff group, only respond when someone @mentions you.
For a client brief, reply with a short outline the team can edit.
For a stock photo, reply with a draft reorder list.
Never share files from ~/business/ in the group unless the person
who asked is on the allowlist.

A salon or small agency gets a shared helper without the bot chiming in on every message.

Prompt 5: A Morning Briefing That Respects The 24-Hour Window

Create a cron job that runs at 07:30 every weekday and sends me,
on WhatsApp: today's jobs from ~/business/jobs.csv, anything flagged
in ~/business/inbox/ as due this week, and one line on what to chase.
Draft only. Do not contact anyone but me.

The cron docs cover scheduling and delivery to messaging platforms.

On the Cloud API, a scheduled message after more than 24 hours of silence fails with Graph error 131047, and Hermes has no template support yet.

So either run this one on the bridge, or reply to the briefing each day to keep the window open.

📞 Want a plan for the marketing side, not just the agent?

Book a free SEO strategy session and my team will look at your website, your content and where AI could help.

→ Book a free SEO strategy session

Running Both Routes On Two Numbers

You don't have to choose for ever: the docs say the bridge and Cloud API adapters can be enabled together, each on its own phone number.

A sensible split is the bridge for the staff group and morning briefings, and the official line for approvals and anything a customer might see.

Give each number its own allowlist, because the bridge reads WHATSAPP_ALLOWED_USERS while the Cloud API reads WHATSAPP_CLOUD_ALLOWED_USERS.

Prompt 1's house rules apply to both, since they live in the agent's memory rather than in either adapter.

On the official line, approvals and clarify questions arrive as tap buttons, which makes Prompt 2's follow-up questions quicker to answer.

A Daily Workflow That Ties The Prompts Together

1. 07:30: the briefing arrives on WhatsApp.
2. During the day: voice notes become job lines, forwarded paperwork lands in the inbox folder.
3. In the staff group: people @mention the agent for outlines and lists.
4. Anything marked DRAFT gets sent by a person, never by the agent.
5. End of day: ask "what did you log today?" and correct anything wrong.

Since v0.23.0 one gateway owns every session on the machine, so you can pick up the same chat at your desk later.

Keep It Tidy: Profiles, Sessions And Re-Pairing

For a separate work number, pair a second profile with hermes -p work whatsapp; the profiles guide explains how profiles stay apart.

The bridge login lives in ~/.hermes/platforms/whatsapp/session; protect it like a password and never commit it.

If WhatsApp updates its Web protocol and the bridge stops, update Hermes and run hermes whatsapp again to re-pair.

On the Cloud API, swap the 24-hour temporary token for a System User permanent token before you rely on it.

For a customer-facing version of these ideas, read our Hermes customer support guide.

A Check-Up To Run When The Chat Goes Quiet

Run `hermes gateway status` and tell me whether WhatsApp is connected.
Then read the last 50 lines of the gateway log and list any WhatsApp
errors in plain English, with the fix the docs suggest for each.
Do not restart, re-pair or edit anything. Report only.

Run it from the desktop or CLI, since a broken WhatsApp link can't carry the answer back to your phone.

The usual causes are a sender missing from the allowlist, a bridge logged out after long inactivity, or an expired Cloud API token.

On the bridge, setting WHATSAPP_DEBUG=true and restarting the gateway writes raw message events to bridge.log.

On the Cloud API, a Graph error 190 usually means the access token has expired or lacks a permission.

What Not To Ask It To Do

• No broadcasts, promotions or messages to lists of people.
• No allow-all setting on an agent that can run commands on your machine.
• No group chats on the Cloud API route, because Hermes doesn't support them there yet.

Each of those fails quietly at first, so keep the allowlist tight and the prompts strict from day one.

Ready for the full system? Join the AI Profit Boardroom.

FAQ

Which Hermes Agent WhatsApp route should I use for my Agent OS?

The bridge for a private agent with staff groups, the Cloud API for an official line with buttons and no ban risk.

Why does the morning briefing fail on the Cloud API?

Meta only allows free-form messages within 24 hours of your last message, and Hermes has no template support yet. Reply daily or use the bridge.

Can the agent reply to customers from these prompts?

No. Prompt 1 tells it to draft only and leave sending to a person, which follows the bridge docs' advice on outbound messages.

How do I add a second WhatsApp number?

Pair another profile with hermes -p work whatsapp, then enable WhatsApp for that profile.

Final word on Hermes Agent WhatsApp

Paste Prompt 1 today, keep every outbound message a draft, and book a free SEO strategy session or join the AI Profit Boardroom when you want help growing your Hermes Agent WhatsApp setup.

Related guides on agentos.guide

→ Hermes Agent Telegram: Run It From Your Agent OS

→ Hermes Agent Slack: Run Your Agent In Slack From Your Agent OS

→ Hermes Agent Discord: Run Your Server Bot In Your Agent OS

→ Grok Bot Phone Calls: Brief, Approve And Log Calls In Your Agent OS

📺 Video notes + links to the tools 👉

🎥 Learn how I make these videos 👉

🆓 Get a FREE AI Course + Community + 1,000 AI Agents 👉

← all guides on agentos.guide