> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hookmyapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hermes Agent

> Connect a Hermes agent to WhatsApp through HookMyApp.

## What you need

| Requirement                                           | Use                                                                                                                            |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Hermes Agent gateway (`Python 3.11+`, `aiohttp 3.9+`) | Runs the HookMyApp platform adapter.                                                                                           |
| HookMyApp account + connected WhatsApp channel        | You can use the sandbox for testing.                                                                                           |
| HookMyApp CLI (`npm install -g @gethookmyapp/cli`)    | Pulls your credentials, sets up transport, and runs diagnostics. The setup wizard can install it for you with `--install-cli`. |

## Install

```bash theme={null}
hermes plugins install hookmyapp/hermes-agent-plugin
pip install aiohttp
```

Hermes doesn't install plugin-specific Python dependencies, so the
`pip install` step is required.

## Set up

```bash theme={null}
hermes hookmyapp setup
hermes gateway restart
```

The wizard prompts for your channel credentials (letting you pick if you have
more than one), writes them to `~/.hermes/.env`, and can install the
HookMyApp CLI for you (`--install-cli`). Secrets are masked in its prompts.
Restart the gateway to pick up the new env.

## Receive messages

**No public URL (default):**

```bash theme={null}
hookmyapp channels listen <channel> --port 8649 --path /hookmyapp/webhook
```

**Your own HTTPS endpoint (servers):**

```bash theme={null}
hookmyapp channels webhook set <channel> --url https://your-host/hookmyapp/webhook
```

## Env values

`hermes hookmyapp setup` writes the first five to `~/.hermes/.env`; the rest
are optional:

| Value                       | What it is                                             |
| --------------------------- | ------------------------------------------------------ |
| `META_GRAPH_API_URL`        | The URL your replies are sent through                  |
| `WHATSAPP_ACCESS_TOKEN`     | Channel token for sending                              |
| `WHATSAPP_PHONE_NUMBER_ID`  | The number your agent sends from                       |
| `WEBHOOK_HMAC_SECRET`       | Verifies incoming message signatures                   |
| `VERIFY_TOKEN`              | Answers HookMyApp's webhook verification probe         |
| `HOOKMYAPP_HOST`            | Listener bind interface (default `0.0.0.0`)            |
| `HOOKMYAPP_PORT`            | Adapter listener port (default `8649`)                 |
| `HOOKMYAPP_WEBHOOK_PATH`    | Webhook endpoint path (default `/hookmyapp/webhook`)   |
| `HOOKMYAPP_CHANNEL_ID`      | Channel id, for diagnostics only                       |
| `HOOKMYAPP_ALLOWED_USERS`   | Comma-separated numbers your agent may answer          |
| `HOOKMYAPP_ALLOW_ALL_USERS` | Set to `true` to answer all senders (dev/testing only) |
| `HOOKMYAPP_HOME_CHANNEL`    | Default recipient for scheduled (cron) messages        |

## Send and receive

Message your WhatsApp number from an allowlisted phone — set
`HOOKMYAPP_ALLOWED_USERS` first, since the adapter answers nobody by
default. Your agent replies in the same chat through Hermes' normal message
loop. `HOOKMYAPP_HOME_CHANNEL` sets the default recipient for cron and
scheduled sends.

## Security

HookMyApp signs every delivery with `X-HookMyApp-Signature-256`. The adapter
rejects unsigned or mis-signed requests, and verification cannot be
disabled. By default the adapter answers only senders in
`HOOKMYAPP_ALLOWED_USERS` (phone formats with or without `+` both match).
Set `HOOKMYAPP_ALLOW_ALL_USERS=true` only for development or testing — it
disables the allowlist entirely. HookMyApp's verification probes are
answered automatically.

## Reliability

Once the adapter acknowledges a message, a crash before your agent processes
it loses that message permanently — HookMyApp and Meta do not re-deliver
acknowledged events. This window is milliseconds wide in normal operation.
One WhatsApp channel per Hermes gateway in this version.

## Diagnostics

```bash theme={null}
hermes hookmyapp status
curl http://localhost:8649/health  # replace 8649 if you changed HOOKMYAPP_PORT
```

## Media limits

Images and documents are cached locally for Hermes vision and document
tools. Voice notes are cached as audio and transcribed by Hermes STT
(faster-whisper locally, or an OpenAI key). Text-like documents are attached
for the agent to read.

## Troubleshooting

**Deliveries return 401.** `WEBHOOK_HMAC_SECRET` in `~/.hermes/.env` does
not match the channel. Re-run `hookmyapp channels env <channel> --write ~/.hermes/.env`, then `hermes gateway restart`.

**Verification probe fails.** `VERIFY_TOKEN` is missing from
`~/.hermes/.env`. Set it and restart the gateway.

**Port 8649 already in use.** Set `HOOKMYAPP_PORT` to a free port in
`~/.hermes/.env`, restart the gateway, and restart `channels listen` with
the new `--port`.

**`channels listen` exited on its own.** A webhook URL set in the HookMyApp
dashboard takes precedence over the CLI listener. Clear it with `hookmyapp
channels webhook clear <channel>` and start `listen` again.

## Source

* Plugin source: [https://github.com/hookmyapp/hermes-agent-plugin](https://github.com/hookmyapp/hermes-agent-plugin) (v0.1.0).
  Installs the `release` branch (production); `main` is staging.
* Developed against Hermes Agent `main`, June 2026 (`3aeded6e`).