--- title: "Hermes Agent WhatsApp plugin: webhook reply routing" description: "Hermes Agent WhatsApp plugin La Boétie keeps in house: reply routing to a business webhook, contacts refreshed every 30 seconds and a clean stop on unlink." canonical: "https://laboetie.io/products/whatsapp-extensions" language: en --- # 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. Status: Private. Access: In house. Routes campaign replies to a business webhook. ## Capabilities - Campaign replies go to a business webhook. - The gateway stops cleanly when WhatsApp unlinks the device. - Older chat messages can be fetched. - A missing patch raises a warning at startup. ## 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. ## 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 | Option | Official? | Good for | Watch out for | |---|---|---|---| | WhatsApp Business Platform | Yes | Business messaging at scale | Templates, approval and per message pricing | | Linked device bridge | No | Personal agents, small internal use | Terms of service, account risk | | WhatsApp Business app | Yes | One small business, by hand | No 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. | Step | Good practice | |---|---| | Reply arrives | It reaches your system with the contact's history | | First response | An agent or a person answers while the intent is fresh | | Opt out | "Stop" ends all contact at once | | Handover | A person takes over on anything sensitive | | Record | The outcome goes back to your CRM | ## Good uses for a WhatsApp agent | Use | Fit | Why | |---|---|---| | Following up on a request someone made | Strong | The person expects your message | | Appointment reminders | Strong | Short and useful | | Support for existing customers | Strong | A familiar channel | | Cold mass messaging | Poor | Consent 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 | Measure | What it tells you | |---|---| | Reply rate | Whether the message was relevant | | Time to first response | Whether your team keeps up | | Handover rate | What the agent cannot answer | | Opt out rate | Whether you are contacting the right people | ## Next step If you want a WhatsApp agent for your business, [send a brief](https://laboetie.io/brief) with your volume, your consent model and the system that should receive replies. [Local User](https://laboetie.io/products/local-user) separates projects on one Hermes gateway, and [Agents](https://laboetie.io/products/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.