# How to set up Hermes Agent on WhatsApp with the Business Cloud API

> Connect business WhatsApp to Hermes with a Meta app, signed HTTPS webhook and allowlist. Understand the 24-hour delivery window.

Canonical: https://hermeswatcher.com/learn/hermes-agent-whatsapp-business-cloud-api-setup  
Section: Learn · Messaging & the gateway  
Last reviewed: Oct 29, 2026  
Basis: Explained from the official Hermes Agent docs and repository (Nous Research). Steps follow the linked official sources.

## What you need

This guide covers the `whatsapp_cloud` adapter, which connects Hermes to Meta's official business messaging API. It is separate from the QR-linked Baileys bridge in [How to set up Hermes Agent on WhatsApp with the Baileys bridge](https://hermeswatcher.com/learn/hermes-agent-whatsapp-setup.md). It does not use a Node.js bridge or QR pairing. Compare routes at [messaging platforms](https://hermeswatcher.com/messaging.md).

You need a configured Hermes model and a host that stays online. A public HTTPS URL is an encrypted address reachable from the internet. Meta calls that address with a webhook, an HTTP request carrying a message or delivery event. A tunnel can forward the public address to a port on your Hermes host.

This walkthrough sets up a private bot for you and named staff. Hermes handles direct chats only. Free-form replies are allowed only within 24 hours of the sender's last message; Hermes does not implement the templates required outside that window.

- A Meta Business account, a Meta app with WhatsApp enabled and a linked WhatsApp Business Account, also called a WABA.
- A dedicated business phone number and access to its Phone Number ID in Meta's API Setup page. The ID is not the phone number.
- An access token, App Secret and webhook verify token. Protect all three like passwords.
- A public HTTPS route to the webhook listener, which uses port 8090 and path `/whatsapp/webhook` by default.
- Optional ffmpeg on the host's PATH for native outgoing voice-note bubbles. Speech features also need configured speech providers.

## Create the Meta app and collect credentials

The official Hermes guide describes these Meta dashboard steps. Open [Meta for Developers: My Apps](https://developers.facebook.com/apps), choose Create App and the use case to connect with customers through WhatsApp, then select a business portfolio. Review Meta's publishing requirements. Open the WhatsApp Quickstart and API Setup, and check that a WABA is linked.

Copy the Phone Number ID from below the From selector in API Setup, then generate an access token. Get the App Secret from Settings → Basic. The App Secret authenticates incoming request signatures. The webhook verify token is a separate shared secret for Meta's initial callback check.

- Temporary access tokens expire after 24 hours. For ongoing operation, follow the official guide's System User token process in Business settings.
- That process creates a system user, assigns the app and WhatsApp assets, then requests `business_management`, `whatsapp_business_messaging` and `whatsapp_business_management`. Check the available token-expiry setting and protect or rotate the result as a long-lived credential.
- In development mode, Meta separately restricts recipients. In API Setup, open To → Manage phone number list and verify each test number (up to five in development mode). This is separate from the Hermes allowlist and is not a substitute for it.

## Connect it to Hermes

Run the dedicated wizard on the Hermes host. It prompts for credentials, checks their form and prints the follow-up tunnel and Meta-dashboard steps. A successful wizard does not establish that incoming messages or replies reached their destination.

Terminal:

```
hermes whatsapp-cloud
```

Generate a verify token, manual setup only:

```
python -c "import secrets; print(secrets.token_urlsafe(32))"
```

For manual setup, use the active profile's .env. The default profile uses `~/.hermes/.env`. Set `WHATSAPP_CLOUD_PHONE_NUMBER_ID`, `WHATSAPP_CLOUD_ACCESS_TOKEN`, `WHATSAPP_CLOUD_APP_SECRET` and `WHATSAPP_CLOUD_VERIFY_TOKEN` to your actual values. Do not substitute a phone number for the Phone Number ID.

The wizard generates a verify token. For manual setup, use the manual verify-token command shown here. Save the result as `WHATSAPP_CLOUD_VERIFY_TOKEN`, then enter the same value in Meta.

The App Secret and verify token are required for this secure inbound walkthrough, even though plugin metadata labels them optional. Without the App Secret, inbound POST delivery is refused with HTTP 503. Never commit .env or paste real credentials into a chat.

## Choose who can talk to it

> **Before you open customer access:** This guide sets up a private bot for you and named staff. If customers can message it, strangers can use your agent and its enabled tools, which can include a terminal on your computer. Before you widen access, read the [official security and command-approval docs](https://hermes-agent.nousresearch.com/docs/user-guide/security) and limit the agent's tools. Keep `WHATSAPP_CLOUD_ALLOW_ALL_USERS` off until you have.

An allowlist is the list of senders permitted to ask the agent to do work. Add only the phone numbers you intend to authorize, with country code and no plus sign, spaces or dashes. Replace the example below with your own number. Keep `WHATSAPP_CLOUD_ALLOW_ALL_USERS` disabled on a private bot.

Active profile .env, replace the example number:

```
WHATSAPP_CLOUD_ALLOWED_USERS=15551234567
```

Unknown requests cannot execute agent work without an explicit grant. Approved pairings and other supported grants also matter; an empty allowlist does not revoke them. Do not expect every stranger to receive a pairing code when a restrictive allowlist or policy is set.

Meta's development recipient list controls which test numbers can receive messages. Hermes authorization controls incoming agent work. Check both before your first message. A valid signature authenticates Meta's webhook transport, not permission for every sender to use your agent.

## Expose the webhook and subscribe to messages

If you need cloudflared, the official guide lists `winget install Cloudflare.cloudflared` on Windows and `brew install cloudflared` on macOS; Linux uses the release binary.

If cloudflared is already installed, the official guide gives the quick-tunnel command below. Run it alongside the gateway. The printed HTTPS address forwards traffic to the local listener. This makes the webhook reachable from the internet, so keep signature validation and the allowlist in place.

Keep the listener port and tunnel target consistent. `WHATSAPP_CLOUD_WEBHOOK_PORT` defaults to 8090. The documented unset webhook host binds to all interfaces on IPv4 and IPv6. Check firewall and tunnel routing instead of assuming this listener is private loopback.

Named profile: under the default multiplexed gateway, a secondary profile's callback is `https://<your-host>/p/<profile>/whatsapp/webhook` on the default profile's shared listener, not port 8090. Use the exact URL logged at startup and target that listener's port. The unprefixed example below is for the default profile.

Separate terminal, with cloudflared installed:

```
cloudflared tunnel --url http://localhost:8090
```

Hermes host:

```
hermes gateway
```

In Meta's WhatsApp Configuration webhook settings, enter the printed HTTPS address followed by `/whatsapp/webhook`, and the exact `WHATSAPP_CLOUD_VERIFY_TOKEN` saved in Hermes. Choose Verify and save. Then subscribe to the `messages` webhook field. Completing callback validation without that subscription does not establish inbound chat delivery.

A quick-tunnel address changes when cloudflared restarts. Update Meta's callback address after a change. For a stable deployment, follow the official guide's named-tunnel or existing HTTPS reverse-proxy instructions. Do not expose unrelated Hermes services while arranging this route.

Block direct public access to port 8090 with your firewall and allow only your proxy or tunnel to reach it.

## Send a first message and inspect the result

From your authorized test phone, send a harmless DM to the business number. Keep the gateway and tunnel terminals open. Check that the message reaches Hermes and that its reply appears in the same conversation. Do not infer success from a saved token or callback handshake alone.

Local webhook health, on the Hermes host:

```
curl http://localhost:8090/health
```

The health response can report `verify_token_configured`, `app_secret_configured` and `ffmpeg_present`. It does not establish that a human message was processed or received. The health endpoint is unauthenticated and reports configuration-presence information; restrict its public exposure at the proxy if needed.

For home-channel deliveries, the Cloud adapter documents `WHATSAPP_CLOUD_HOME_CHANNEL`. Check the actual configured delivery target. Chat-created jobs default to their origin; a home destination is not a universal override. See [Hermes Agent task finished but no message arrived](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md).

## What it can do

- Text, incoming images, documents and voice notes are documented. Incoming voice notes use your configured speech-to-text provider.
- Outgoing images, videos, documents and text-to-speech audio are documented. With ffmpeg available, speech can be converted to a native WhatsApp voice note; otherwise it falls back to an MP3 attachment.
- Native buttons support clarification, command approvals and slash-command confirmations, with text fallback. Read receipts and a typing indicator are documented.
- The overview table marks voice, images, files and typing for Cloud API. It does not mark threads, reactions or streaming. The current Hermes adapter handles DMs only, even if a Meta account has other platform capabilities.
- Local faster-whisper is the usual local transcription engine, but it is unavailable on native Windows ARM64 or Intel macOS (repository package markers); use a hosted speech-to-text provider there.

## Understand the 24-hour delivery limit

Meta permits free-form outbound replies within 24 hours of the user's last inbound message. Outside that window, Meta requires an approved message template. The current Hermes Cloud adapter does not implement template sending, so this guide cannot provide a template workaround.

A scheduled notification or long-running result can fail with Graph error `131047` after the window closes. The user can send a new DM to reopen the window. Choose another appropriate delivery destination if the task must notify you after a long quiet period. An official API does not remove account, review or delivery requirements.

## Keep it running

The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep.

After checking foreground behavior, stop that foreground gateway before starting its installed service. Keep the host, internet connection and tunnel available. If the computer is off or asleep, Hermes cannot process incoming messages or run jobs. A background service does not keep a powered-off host running.

Install the gateway service:

```
hermes gateway install
```

Start the service:

```
hermes gateway start
```

Check actual running state:

```
hermes gateway status
```

Apply credential or configuration changes:

```
hermes gateway restart
```

The gateway service does not install or supervise your separate tunnel process. Keep that running using the provider's documented deployment method. Windows Task Scheduler watches the gateway launcher rather than later gateway crashes, so check status and start it again if needed.

Rotate compromised access tokens and App Secrets. Keep .env and copied diagnostics private. See [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md) and [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md) for host and service choices.

## If it doesn't answer

- Callback validation fails: check the current HTTPS address, path, exact verify token and running gateway. Keep the App Secret configured.
- No inbound messages: check the `messages` subscription, request signature errors, Hermes allowlist and Meta development recipient settings separately.
- Graph error 100: check the Phone Number ID, not the phone number. Graph error 190: check token expiry, revocation and required permissions.
- Graph error 131047: the 24-hour window expired. Current Hermes has no template-sending implementation.
- Voice transcription is empty: check the configured speech provider and its dependencies or credentials. For the default local provider, request its dependency in the activated, PM-prepared Hermes source checkout with the command below (PM is the Hermes package manager). Missing ffmpeg affects outgoing voice-note formatting rather than granting voice access.
- For the wider diagnostic path, see [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) and [Hermes Agent task finished but no message arrived](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md).

Voice transcription fix, activated Hermes source checkout:

```
python -c "import pm; pm.sync_venv(['stt-whisper'], explicit=True)"
```

## Official docs

Reviewed Oct 29, 2026 against the official Hermes docs.

[Official Hermes WhatsApp with the Business Cloud API docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/whatsapp-cloud)

## Related guides

- [All messaging platforms](https://hermeswatcher.com/messaging.md)
- [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md)
- [How to set up Hermes Agent on WhatsApp with the Baileys bridge](https://hermeswatcher.com/learn/hermes-agent-whatsapp-setup.md)
- [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md)
- [Hermes Agent task finished but no message arrived](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md)
- [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md)

## Related tools

- [WhatsApp: chat with Hermes from your phone](https://hermeswatcher.com/tools/whatsapp.md)
- [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md)
- [Command approvals: decide what the agent may run unattended](https://hermeswatcher.com/tools/approvals-security.md)
- [Scheduled tasks: automate a proven run](https://hermeswatcher.com/tools/scheduling.md)

## Sources

- [WhatsApp Business Cloud API, official Hermes guide](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/whatsapp-cloud)
- [Cloud API guide at the research snapshot](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/messaging/whatsapp-cloud.md)
- [Gateway operation and service lifecycle](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/)
- [Gateway authorization and pairing policy (pinned source)](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/gateway/authz_mixin.py#L653-L773)
- [Scheduled delivery options](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron)
- [Voice mode and speech-provider requirements](https://hermes-agent.nousresearch.com/docs/user-guide/features/voice-mode)
- [Gateway feature comparison at the research snapshot](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/messaging/index.md#L31-L67)
- [website/docs/user-guide/multi-profile-gateways.md](https://raw.githubusercontent.com/NousResearch/hermes-agent/main/website/docs/user-guide/multi-profile-gateways.md)
- [pyproject.toml](https://raw.githubusercontent.com/NousResearch/hermes-agent/main/pyproject.toml)

---

HermesWatcher is an independent guide. It is not affiliated with or endorsed by Nous Research. The [official Hermes Agent documentation](https://hermes-agent.nousresearch.com/docs) and [repository](https://github.com/NousResearch/hermes-agent) from Nous Research are the authority; each page here lists the official sources it was written from. If this site and the official docs disagree, trust the official docs. Index for agents: https://hermeswatcher.com/llms.txt