Official Meta Business Partner

Connect Hermes
to WhatsApp

Give your Hermes agent a WhatsApp number on the official API. Install the Kapso plugin, run setup, and message your agent from your phone.

Get started Read docs

What you can send

Messages reach Hermes through the official WhatsApp API. It replies in the same chat, with whatever tools you have given it.

12:31
Hermesonline
Today

Find a ramen place near the office that takes reservations

12:30

Two places take reservations within a ten-minute walk: Menya Kaito, 6 min walk, books online Hokkai Ramen Bar, 9 min walk, by phone Want the address for one of them?

12:31
Message

Setup

Paste the prompt into Hermes, or run the commands yourself.

Paste a prompt

Hermes installs the plugin and asks you for the key and a public URL.

Paste this into Hermes

>Connect yourself to WhatsApp with Kapso. Follow the steps at kapso.com/whatsapp-hermes-agent and ask me before creating any keys.

  • Reads this page and the Kapso docs
  • Installs the Kapso plugin
  • Waits for your API key and public URL

Run the commands

Needs Hermes running and a Kapso number. About five minutes.

  1. 1. Install the plugin

    It asks for your Kapso API key.

    hermes plugins install gokapso/hermes-agent-plugin --enable

  2. 2. Expose the webhook

    Kapso needs a public HTTPS URL for port 8648. Tailscale Funnel is one way.

    tailscale funnel --bg http://127.0.0.1:8648

  3. 3. Run setup and restart

    Setup picks your number, creates the webhook, and saves its secret.

    hermes kapso setup --install-cli \
  --funnel-url https://<your-funnel-host>
hermes gateway restart
For scripts and CI, use the Kapso CLI with the same key: npm install -g @kapso/cli
CLI docs →

For AI agents
reading this page

Hermes can read this page and connect itself. Or copy the instructions and paste them into any agent with shell access to the Hermes machine.

Instructions for AI agents

## For AI agents reading this page

You are reading https://kapso.com/whatsapp-hermes-agent. Kapso is the WhatsApp API for developers. Its Hermes plugin gives a Hermes Agent a WhatsApp number through the official WhatsApp API: direct messages with text, images, voice notes, and documents. Follow these steps to connect it. Run them non-interactively.

  1. 1.

    Check what the user has.
    Hermes must be installed with the gateway running (hermes gateway status). The user needs a Kapso project API key and a WhatsApp number connected in Kapso. Never create keys, sign up, or connect numbers on their behalf.

  2. 2.

    Install the plugin. Run:

    hermes plugins install gokapso/hermes-agent-plugin --enable --yes-deps

    Without --yes-deps a non-interactive install skips the plugin’s Python dependency and leaves it disabled. Ask the user to put KAPSO_API_KEY in ~/.hermes/.env rather than pasting it into chat.

  3. 3.

    Get a public HTTPS URL.
    Kapso must reach port 8648 on this machine. If Tailscale Funnel is running, read the URL from tailscale funnel status. Otherwise ask the user for one; do not open tunnels yourself.

  4. 4.

    Run setup. Run:

    hermes kapso setup --no-prompt --install-cli --configure-webhook \
  --phone-number-id <id> --home-channel <wa_id> --allowed-users <wa_id> \
  --funnel-url https://<public-host>

    Use the user’s own WhatsApp number for --home-channel and --allowed-users. Find the phone number ID with kapso whatsapp numbers list.

  5. 5.

    Restart and verify.
    Run hermes gateway restart, then hermes kapso status and curl http://127.0.0.1:8648/health. If either fails, stop and tell the user what it printed.

  6. 6.

    Report back.
    Tell the user which number Hermes answers on and ask them to send it a message.

## Reference

Plugin
gokapso/hermes-agent-plugin
Webhook
https://<public-host>/kapso/webhook
Local port 8648 · health at /health
Env
KAPSO_API_KEY, KAPSO_WEBHOOK_SECRET, KAPSO_PHONE_NUMBER_ID
Optional: KAPSO_HOME_CHANNEL, KAPSO_ALLOWED_USERS
Supports
Direct messages: text, images, voice notes, documents
Docs
https://docs.kapso.ai/docs/whatsapp/hermes-agent

Other agents and tools

Frequently asked
questions

No. Start with a Kapso number or connect your own WhatsApp number.

The Kapso plugin connects Hermes through the official WhatsApp API, so there is no Meta app to set up. Kapso manages the number, and plugin setup creates the webhook and its secret.

No. You run Hermes on your own machine or server. Kapso provides the WhatsApp connection.

Hermes with the gateway running, a Kapso API key, a connected number, and a public HTTPS URL for port 8648. Node.js and npm are needed if setup installs the Kapso CLI.

Restart the gateway, run hermes kapso status, and check that your public URL reaches http://127.0.0.1:8648/health. The troubleshooting guide in the docs covers webhook, number, and voice-note issues.

Give your Hermes agent
a WhatsApp number

The free plan includes a sandbox number and 2,000 messages a month.

Get started