How to connect Hermes to your WhatsApp business number

What you need

• Hermes Agent installed and working on a computer or small server. Nous Research's Hermes docs cover installing it.
• A Spaces account. The Free plan starts when you connect a chat account, with no card needed.
• Your business WhatsApp number, and the phone it lives on to scan a QR code.
• A short list of the questions customers ask most, with your answers, plus what you never want promised.
• A machine that stays on during the hours you want Hermes to answer.

Step 1: connect your WhatsApp account to Spaces

You scan a QR code with the phone that has the number, the same way you would link WhatsApp on a computer. Your account stays yours, and you keep using it on your phone as normal.

Once it is connected, the account shows in your Spaces dashboard. Connecting does not send anything. It only means Spaces can read and send on that account when an AI agent you have added asks it to.

Use the number your customers already know. A number with a real history of conversations is treated with less suspicion than a brand-new one. On WhatsApp, new chats wait up to 24 hours after connecting. Replies to people who wrote in go out from the first day.

Step 2: add Spaces to Hermes

1. Add the block below to ~/.hermes/config.yaml.
2. Run hermes mcp login spaces and sign in to Spaces in the browser.

mcp_servers:
  spaces:
    url: "https://api.spacesos.com/mcp"
    auth: oauth

To check it worked: Run /reload-mcp, then hermes mcp test spaces. The tools appear as mcp_spaces_….

Prefer an API key? Use a header instead of auth: oauth.

mcp_servers:
  spaces:
    url: "https://api.spacesos.com/mcp"
    headers:
      Authorization: "Bearer spc_live_…"

You sign in on Spaces' own page during this step, so Hermes never sees your WhatsApp login or your Spaces password. If Spaces does not show up:

• Check the address is exactly https://api.spacesos.com/mcp, with nothing added at the end.
• Run the sign-in step again, in case the first sign-in in the browser did not finish.
• Restart Hermes so it reads the new settings.
• If it still does not appear, the Hermes Agent MCP docs have the current steps, and our Hermes setup page has ours.

Step 3: try it

Start Hermes and ask in plain words. Start with requests that only read:

• List my Spaces accounts and tell me which one is WhatsApp.
• Summarise the WhatsApp chats that are waiting for a reply.
• Draft replies to the price questions from the business brief, and do not send them yet.
• Which customers asked about a date next week?

Start with a question that only reads, like the first one. It shows you that Hermes can see your WhatsApp messages before you let it send anything. Then try a draft, read it carefully, and only then let it send.

Good to know

Hermes is an always-on agent. Unlike Claude, ChatGPT or Grok in a browser, it does not wait for you to open a chat, so it can reply to a customer at 11am while you are elbow-deep in a job. That is the point of it, and it is also why the first week should be about drafts rather than sending.

Hermes tells you about handed-over chats wherever you talk to it, such as its terminal or a chat app you have set it up with.

Hermes names the Spaces tools mcp_spaces_ followed by the tool name, such as mcp_spaces_wait_for_events. If you read its logs, that is what you will see.

A Spaces routine sends a set reply you wrote in advance when something happens, such as a message after hours. It is not an AI, and it runs on Spaces, so it keeps working if the Hermes machine goes down.

Give Hermes one channel or all of them

The address in Step 2 covers every channel you connect to Spaces. If you only want Hermes to reach WhatsApp, use https://api.spacesos.com/mcp/whatsapp in the config instead. It uses the same sign-in and limits, and it only shows Hermes your WhatsApp accounts. That is a sensible start: a new agent that can only see one channel can only make mistakes on one channel.

If you run more than one WhatsApp number, such as one for bookings and one for the shop, each number is its own account in Spaces with its own limits. Tell Hermes which number each kind of question belongs to.

Standing instructions for Hermes

Keep the facts customers ask about in the Spaces business brief, which every agent reads. Hermes can set it up for you: ask it to follow the brief step, answer its short questions, and it saves your answers. Then give Hermes standing instructions about how to behave. An example:

You answer WhatsApp for Muddy Paws, a mobile dog groomer.
Read the Spaces business brief before every reply and never contradict it.
Listen with wait_for_events. Never check the chat list in a loop.
Answer: prices, the areas we cover, what each groom includes, how to book.
Never: confirm a booking time, give health or skin advice, or offer a discount.
Hand to me: anything about a bite, an injury, a complaint, a refund or an anxious dog.
When you hand a chat over, tell me and stop replying in that chat.
Replies only between 8am and 7pm. Outside those hours, do nothing.
If Spaces refuses a send, wait for the time it gives. Never reword a message to get round a limit.

The line about hours matters. Spaces does not let you set working hours on an account for live replies, so if you want quiet evenings, say it in the instructions or stop Hermes at night.

A worked example: a day on the road

Here is how part of a day might go for a mobile dog groomer who works from a van and cannot touch the phone between dogs. Names and details are examples.

Hermes answered the price and the area at once, from the brief. When the customer mentioned a nervous dog, it stepped back, as the instructions said. The owner picked the chat up at lunchtime with everything she needed in one line.

What Hermes should answer and what it should leave

How Hermes should check for messages

Ask it to call wait_for_events, which waits until something new arrives and returns it at once, then to call it again with the next_cursor it was given. Checking the chat list over and over looks like a bot to the platforms, and wait_for_events does not touch the platform at all.

If Hermes runs on a server with its own web address, Spaces can also send each event to that address as a webhook instead. Either way, the rule is the same: let Spaces tell Hermes about new messages, rather than having Hermes go looking.

WhatsApp rules Spaces keeps to

• A new chat only goes to someone who has messaged your number before, or whom you marked as opted in on the Accounts page.
• The first message to someone new is plain text, with no links, photos, files or voice notes.
• New chats and follow-ups go out between 8:00 and 21:00 local time. A reply to someone who wrote in the last two hours goes out at any time.
• The same or nearly the same message goes to at most 2 new people a day, so your agent writes each first message for the person it is going to.
• Anyone who says stop, unsubscribe or similar, in English, French or Spanish, is never messaged again from that number.

Replies wait a short random time before they go, and WhatsApp shows "typing…" first, so they arrive the way a person's would. Messages are always at least 10 seconds apart.

Drafts first, then let it send

Ask your AI agent to hold replies as drafts, and nothing goes out until you approve it. Hermes switches this on for you with set_approvals. While it is on, you ask Hermes to list what is waiting and approve or reject each reply. Once the drafts are reliably right for prices and areas, ask Hermes to stop holding replies, and keep the hand-over rules in its instructions for everything else.

If Hermes ever sends something you did not expect, pause all sending in Spaces under Settings, then Pause everything. Reading keeps working, so you can see exactly what happened before you start again.

Keep the machine running

• Run Hermes on a machine that does not go to sleep, such as a small always-on computer or a server.
• Check now and then that Hermes is still running. If it stops, messages simply wait in WhatsApp until it starts again.
• Keep the phone with the WhatsApp number charged and online, because a linked device depends on it.
• If the WhatsApp link drops, scan the QR code again from the Spaces dashboard. Our guide on reconnecting covers what to expect.

Common mistakes to avoid

• Letting Hermes send from the first hour. Start with drafts.
• Giving it every channel on day one. Start with the WhatsApp-only address.
• Leaving the hours out of the instructions, so it replies at midnight.
• Using it to message old customers about an offer. WhatsApp's terms prohibit bulk messaging, and Spaces refuses the same text to many new people.
• Forgetting to update the brief when prices change, so Hermes keeps quoting the old ones.

Summing up

With Spaces, Hermes can look after your business WhatsApp while you work: answering the questions that always have the same answer, and handing the rest to you with a short note. Use the WhatsApp-only address to start, write clear standing instructions, listen with wait_for_events, hold replies as drafts at first, and keep the machine running.

How Spaces keeps your account safe

Whatever you ask, Spaces keeps your WhatsApp account inside safe limits: at least 10 seconds between messages, up to 400 a day, and 10 new conversations a day at most, with a gentler start for a newly connected account. If your AI tries to go faster, Spaces holds the message and says when it can try again.

New conversations warm up over the first weeks after you connect:

A reply to someone who wrote in is never held back by the daily limits, so customers get answers from the first day. Only messages that are not replies to someone who wrote in count toward the messages a day, which rise each week of the warm-up.

These are Spaces' own limits. They lower the risk of a restriction, but they cannot remove it, because WhatsApp makes its own decisions about accounts. Read the note at the top of this page before you connect.

Pricing

Free to start, then $9 per connected account a month

What is Hermes Agent?

Hermes Agent is an open-source AI agent from Nous Research that you run on your own computer or server. Because it keeps running, it can answer messages without you opening a chat each time.

Can Hermes answer WhatsApp while I am working?

Yes, as long as the machine it runs on stays on. It listens for new messages through Spaces and answers from your brief and instructions. Start with drafts before you let it send.

Does this use the WhatsApp Business Platform?

No. Spaces links your own number with a QR code, like WhatsApp on a computer. WhatsApp's own terms apply, so read the note at the top of this page.

Can I limit Hermes to WhatsApp only?

Yes. Use https://api.spacesos.com/mcp/whatsapp in the Hermes config instead of the main address. Hermes then sees only your WhatsApp accounts, with the same limits.

How do I take over a chat from Hermes?

Ask Hermes to hand the chat to you, or put the hand-over rules in its instructions. It then stops replying in that chat until you hand it back.

Can Hermes book appointments for me?

Spaces does not connect to booking systems or diaries. Hermes can offer to pass dates on while you confirm, or you can give Hermes access to your diary through its own tools.

What if the Hermes machine goes down?

Messages wait in WhatsApp until it is back, and wait_for_events picks up from where it got to. A Spaces routine can send a set holding reply in the meantime, because routines run on Spaces itself.

Can I use an API key instead of signing in?

Yes. The Hermes config can send a header with your Spaces key instead of using auth: oauth, as shown in Step 2. Keep the key out of anything you share.