What is the Kapso Hermes Agent plugin?

The Kapso Hermes Agent plugin lets a Hermes Agent gateway receive Kapso WhatsApp webhooks, turn inbound WhatsApp messages into Hermes MessageEvents, and send replies through Kapso.

What does Hermes Agent setup require?

It requires a Hermes gateway, a Kapso API key, a connected Kapso WhatsApp number, a public HTTPS URL, and a webhook secret for signed webhooks.

Can Hermes Agent receive WhatsApp media?

Inbound images are downloaded through Kapso, cached, and attached to Hermes MessageEvents. Inbound audio and voice notes can be cached for Hermes STT.

Connect Hermes Agent to WhatsApp

Use the Kapso Hermes Agent plugin when a Hermes Agent gateway needs to receive Kapso webhooks, create Hermes MessageEvents, and send WhatsApp replies through Kapso.

Start building Read Hermes Agent docs

Route WhatsApp through the Hermes gateway

The Kapso Hermes Agent plugin keeps WhatsApp transport, webhook verification, sender numbers, and media handling close to the Hermes gateway.

Install the plugin

Install the Kapso Hermes Agent plugin and enable it in the Hermes gateway.

Receive Kapso webhooks

The adapter listens for POST /kapso/webhook and turns inbound WhatsApp messages into Hermes MessageEvents.

Send replies through Kapso

Use the connected Kapso WhatsApp number as the sender for Hermes replies and cron delivery.

Restrict allowed users

Use KAPSO_ALLOWED_USERS or local development-only KAPSO_ALLOW_ALL_USERS for inbound access control.

Handle images and voice notes

Inbound images and audio can be downloaded through Kapso, cached, and attached to Hermes media fields.

Check gateway health

Use hermes kapso status and gateway health checks after setup or env var changes.

Install and run setup

The setup command can install the Kapso CLI, list connected WhatsApp numbers, ask which number Hermes should use, generate a webhook secret, and create the phone-number webhook.

Hermes Agent setup

hermes plugins install gokapso/hermes-agent-plugin --enable
hermes kapso setup --install-cli --funnel-url https://<your-funnel-host>
hermes gateway restart

Requires a Hermes Agent gateway.

Requires KAPSO_API_KEY and a connected Kapso WhatsApp number.

Requires a public HTTPS URL for Kapso Cloud webhooks.

Restart the Hermes gateway after enabling the plugin or changing env vars.

What the plugin handles

Hermes remains the agent runtime. Kapso supplies official WhatsApp connectivity, webhook delivery, sender identity, and media access.

Public webhook

The default adapter accepts POST /kapso/webhook and should be reachable through a public HTTPS URL.

Signed events

Use KAPSO_WEBHOOK_SECRET for signed Kapso webhooks. Disable verification only for unsigned local fixtures.

Media and STT

Images are cached for native vision processing, and audio or voice notes can be cached for Hermes STT.

Put Hermes Agent on an official WhatsApp number

Connect a Kapso sender, configure the gateway webhook, and let Hermes receive and reply to WhatsApp messages through Kapso.

Start free Read Hermes Agent docs