La Boétie
Send a brief

WhatsApp Extensions: Hermes Agent plugin

WhatsApp Extensions is a Hermes Agent WhatsApp plugin for reply routing from listed contacts to a business webhook, a clean gateway stop when WhatsApp unlinks the device and retrieval of older chat messages. The routed contact list refreshes every 30 seconds. La Boétie keeps version 1.1.0 in house, and the plugin has no public install.

Send a brief

Routes campaign replies to a business webhook

Status
Private
Access
In house

WhatsApp Extensions capabilities

Routing WhatsApp replies to a webhook

A direct message from a listed contact goes to a business webhook before gateway auth, so the sender gets no agent turn and no pairing reply. The webhook receives the sender, the text and any attachments up to 12 MB. The contact list refreshes every 30 seconds. Other unknown senders reach gateway auth as usual.

When WhatsApp unlinks the device

When WhatsApp unlinks the device, the bridge exits with code 78. The adapter then stops reconnecting and reports the logout. An operator has to link the device again by hand.

Fetching older WhatsApp messages

A local history request asks the phone for messages older than a known message in a chat. The caller gives the chat, a message count and that anchor message. The request sends nothing to the contact.

Patches and Hermes updates

The logged out exit and the history fetch need patches to Hermes Agent, because no plugin hook reaches that code. After every Hermes update, a script applies the patches again and the gateway restarts. The script skips any patch already in place and exits non zero when a patch no longer fits. Each gateway start logs any missing patch.

How La Boétie uses WhatsApp Extensions

La Boétie keeps the plugin in house on its Hermes gateway. The repository is private, so no public package or install path exists. A team working on WhatsApp and an agent gateway can send a brief describing what it needs to connect.

On this page

What this plugin adds to Hermes Agent

Hermes Agent is an open source AI agent by Nous Research, with a gateway that connects it to messaging apps. Its WhatsApp adapter lets a person talk to an agent. A business has more needs: replies from campaign contacts must reach its own system, a lost connection must be visible, and older messages may be needed for context.

WhatsApp Extensions adds those parts. Hermes updates replace the agent's own code, so local WhatsApp work lives in a plugin and a small set of patches that survive an update.

How reply routing works

A business sends a message to a contact, and the contact answers. The plugin recognises replies from contacts on your list and sends them to your business system through a webhook. Unknown senders receive no reply, which keeps a business number quiet.

When WhatsApp unlinks the device

A linked device can be logged out: a user removes it from the phone, or WhatsApp ends the session. With this plugin the gateway stops cleanly and reports the event, so your team knows at once that someone must link the device again.

Fetching older messages

An agent that joins a conversation late lacks context. The plugin can fetch older messages of a chat from the phone, which must be online. Treat old messages as personal data, and store only what the task needs.

WhatsApp API options compared

OptionOfficial?Good forWatch out for
WhatsApp Business PlatformYesBusiness messaging at scaleTemplates, approval and per message pricing
Linked device bridgeNoPersonal agents, small internal useTerms of service, account risk
WhatsApp Business appYesOne small business, by handNo automation

The Hermes WhatsApp bridge is a linked device client. It relies on an unofficial library, so WhatsApp can change its behaviour or restrict the account. For customer messaging at volume, use the official Business Platform.

Consent

Messaging people on WhatsApp is direct marketing in most of Europe. You need a lawful basis, an easy way to stop and respect for WhatsApp's own rules on business messaging. A plugin that routes replies has no opinion on who should have been contacted, so that decision stays with you.

Designing a reply workflow

A campaign reply needs an owner within minutes, since a conversation goes cold quickly.

StepGood practice
Reply arrivesIt reaches your system with the contact's history
First responseAn agent or a person answers while the intent is fresh
Opt out"Stop" ends all contact at once
HandoverA person takes over on anything sensitive
RecordThe outcome goes back to your CRM

Good uses for a WhatsApp agent

UseFitWhy
Following up on a request someone madeStrongThe person expects your message
Appointment remindersStrongShort and useful
Support for existing customersStrongA familiar channel
Cold mass messagingPoorConsent problems and account risk

Keeping an account healthy

  • Message people who asked to hear from you.
  • Keep volume steady, with no sudden bursts.
  • Personalise each message.
  • Honour every opt out.
  • Watch for blocks and reports.
  • Keep a clear business profile.

Accounts that many people block or report can lose access, so these habits protect your number as well as your reputation.

What to measure

MeasureWhat it tells you
Reply rateWhether the message was relevant
Time to first responseWhether your team keeps up
Handover rateWhat the agent cannot answer
Opt out rateWhether you are contacting the right people

Next step

If you want a WhatsApp agent for your business, send a brief with your volume, your consent model and the system that should receive replies. Local User separates projects on one Hermes gateway, and Agents offers a team workspace on the same engine.

Frequently asked questions

Can Hermes Agent work with WhatsApp?

Yes. Hermes Agent has a WhatsApp gateway, and WhatsApp Extensions adds to it through a plugin hook and patches. The additions cover reply routing to a business webhook, a clean stop on device unlink, fetching of older messages and a startup warning for missing patches. The plugin depends on Hermes Agent by Nous Research and runs inside its gateway.

How does reply routing treat unknown WhatsApp senders?

The plugin reads each direct message before gateway auth and sends a message from a routed contact to the webhook. The gateway then drops that message. Every other unknown sender reaches gateway auth. There the setting unauthorized_dm_behavior: ignore drops the message with no reply. Removing that setting sends pairing replies to strangers again.

Does reply routing need a public URL on the gateway?

No. The plugin makes outbound calls, so reply routing needs no public listener on the gateway. The plugin gets the routed contact list from one URL and sends each message to a second URL as a POST. A shared secret travels in a header on both calls. Routing stays inactive when any of the three settings is missing.

What happens when the webhook call fails?

The gateway logs a failed POST and drops the message. A 404 from the webhook means the receiving system has no open conversation for that contact. Attachments over 12 MB are skipped with a warning in the log. In these cases the sender gets no agent turn, which leaves every follow up to the receiving system.

Will a Hermes update break the plugin?

The plugin folder survives a Hermes update, while the patches need applying again because an update replaces the agent code. A script handles this: it skips a patch already in the tree and exits non zero when upstream changed those lines. At each gateway start, the plugin writes any missing patch to the error log.

Can I install WhatsApp Extensions?

No. The repository is private and has no LICENSE file, and the plugin stays in house at La Boétie as version 1.1.0. It has no public package and no install path. Teams that want WhatsApp connected to an agent gateway can describe their setup in a brief from this page, and the studio will reply from there.