Skip to main content

​
What you need

​
Install

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

​
Set up

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):
Your own HTTPS endpoint (servers):

​
Env values

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

​
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

​
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