Channels and messaging

Each agent can receive messages through its own Hermes Gateway configuration. Hermina currently exposes guided flows for WhatsApp, Telegram, and Matrix, with room for other Hermes-supported platforms.

Choose a channel

Channel	Setup style	Best for	Key consideration
WhatsApp (Baileys)	Linked-device QR	Fast personal or business-number setup	Session credentials must persist
WhatsApp Cloud	Meta app credentials + webhook	Official API deployments	Requires a public HTTPS webhook
Telegram	Bot token	Bots, groups, and simple deployment	Group mention policy matters
Matrix	Homeserver, user, token, room policy	Self-hosted/open messaging	Treat the access token as a secret

Configure channels from the agent detail screen or during hermina onboard. Use the CLI commands below for common operations.

WhatsApp linked device

The default WhatsApp transport uses a linked device session.

hermina start support
hermina qr support
hermina logs support --follow

On the WhatsApp account that will represent the agent:

Open Settings or the main menu.
Open Linked devices.
Choose Link a device.
Scan the terminal QR.

Credentials are stored under agents/<name>/whatsapp/session/. Preserve that directory during updates and backups.

Check the connection:

hermina bridge support

If the QR has expired, restart the agent and follow the new QR from the logs.

WhatsApp Cloud

WhatsApp Cloud uses Meta credentials and a webhook instead of a device QR. Configure the transport and secrets through the dashboard or hermina channel:

hermina channel support \
  --transport=whatsapp-cloud \
  --cloud-phone-number-id=PHONE_NUMBER_ID \
  --cloud-access-token=ACCESS_TOKEN \
  --cloud-app-secret=APP_SECRET \
  --cloud-verify-token=VERIFY_TOKEN \
  --cloud-waba-id=WABA_ID

The webhook must be reachable over HTTPS and routed to the published Cloud webhook port. If the port mapping changes after the container was created, recreate the runtime so Docker publishes the new port.

Create a bot with BotFather, then add its token from the agent's Channels settings or guided onboarding. After saving, restart the agent and send the bot a direct message.

Control group behavior with:

hermina telegram-groups support on

With mention mode on, the bot responds in a group only when mentioned or when a message replies to it. With it off, it can respond to every group message; use that mode carefully in busy rooms.

Matrix

hermina matrix support \
  --homeserver=https://matrix.example.com \
  --user-id=@support:example.com \
  --access-token=YOUR_ACCESS_TOKEN \
  --allowed-rooms='!roomid:example.com' \
  --require-mention=true \
  --restart=true

Restrict users or rooms before joining public spaces. A Matrix access token grants the permissions of its account.

Direct messages, groups, and allowlists

Channel connectivity and message authorization are separate. A healthy bridge can still ignore a sender because of allowlist, group, or command policy.

Set allowed WhatsApp users:

hermina allowlist support --numbers=5511888888888,5511777777777

Enable or disable WhatsApp group replies:

hermina groups support on
hermina groups support off

When WhatsApp groups are enabled, the generated policy requires a mention by default.

See Access and permissions for slash-command administrators and network security.

Channel troubleshooting order

Confirm the agent runtime is running with hermina list.
Confirm the model responds in dashboard chat.
Check the channel status or bridge health.
Inspect agent logs.
Check allowlist and group policy.
Send /whoami to learn the platform's exact sender ID.
Re-pair or rotate the platform token only after the previous checks pass.