zeronode / module-web-agent

dev-main 2026-09-28 14:35 UTC

Requires

• php: >=8.1
• magento/framework: >=103.0.0
• magento/module-catalog: >=104.0.0
• magento/module-checkout: >=100.4.0
• magento/module-cms: >=104.0.0
• magento/module-store: >=101.0.0

proprietary

• chat
• ai
• magento2
• shopping assistant

Published on Packagist.org on 2026-09-28 14:35 UTC

README

Embeds the Zeronode AI shopping assistant (Hermes) on the storefront and lets it act on the store: add products to the visitor's cart, open product pages, open the cart and apply coupons. Every action asks the visitor to confirm.

The widget's look, texts, languages and behaviour come from the agent's configuration in the Zeronode admin; the store only needs the agent's public key.

Requirements

• Magento Open Source / Adobe Commerce 2.4.x or Mage-OS, PHP 8.1+
• A Zeronode agent with a public embed key (zn_pub_...) whose catalogue integration points at this store (Zeronode admin > agent > Catalog, preset Magento; see "Catalogue access" below)

Install

composer require zeronode/module-web-agent
bin/magento module:enable Zeronode_WebAgent
bin/magento setup:upgrade
bin/magento cache:flush

Production mode also needs bin/magento setup:di:compile and setup:static-content:deploy, as for any module.

Uninstall

bin/magento module:uninstall Zeronode_WebAgent

That takes the module's own settings with it (widget state, public key, preview token and the encrypted account token) and nothing else: the module creates no tables, and Setup\Uninstall only clears rows in its own zeronode_web_agent/... config section.

Two things survive on purpose. The "Zeronode" integration this store may have created keeps existing under System > Integrations; delete it there if the catalogue connection is no longer wanted. And nothing on the Zeronode side is touched, so the agent and its embed key stay as they are.

module:uninstall only runs for a module installed through Composer. A copy dropped into app/code is removed by deleting its directory, and its config rows then stay behind: delete the zeronode_web_agent/... rows from core_config_data by hand if you want them gone.

Configure

Stores > Zeronode Web Agent:

1. Sign in with your Zeronode account: an emailed code, a password, or paste one agent's embed key (znpub...) to skip the account.
2. Choose the assistant, set who can see it (live / preview link), the look (colours, corners, position, title, picture), the voice (house style).
3. Store: "Connect this store" and Save. The module creates an API integration named Zeronode in this Magento (System > Integrations, catalogue and stock read access), activates it and sends its keys to Zeronode; the assistant then reads this store's catalogue over the REST API. Keys are not kept in Magento.
4. Store actions: whether the assistant may add to cart, open product pages, open the cart and apply coupons (visitors confirm each action).
5. Knowledge: scan pages of your site into the assistant's knowledge base.

Save mints (or reuses) an embed key locked to this store's address and turns the widget on. The account token is stored encrypted in Magento's config and only ever used server-side.

There is no Stores > Configuration section. For development (another Zeronode backend or widget build) override the defaults in app/etc/env.php:

'system' => ['default' => ['zeronode_web_agent' => ['advanced' => [
    'api_base' => 'https://api.example',
    'ws_url' => 'wss://api.example/v1/embed/ws',
    'widget_src' => 'https://content.example/zeronode-plugin.js',
]]]],

Several websites and store views

The settings are saved in the default scope, so one assistant serves the whole installation. What the module derives per scope:

• The embed key is registered for every active store view's own base url (plus the www/apex counterpart of each real domain), so a second website on its own domain connects as well. Adding a website later: press Save once, the key is re-registered with the new origin.
• The catalogue url is rest/{store}/V1 whenever there is more than one store view, so the agent reads prices and stock in the scope it asks for.
• The store actions run on whichever store view the visitor is on: the cart add, the coupon and the product url all come from that store view's own url, and Magento keeps a separate cart per website.
• A product that is not assigned to that website cannot be added there; Magento's own message is passed back to the assistant.

Connecting the catalogue

In Stores > Zeronode Web Agent, the Store section asks how to connect:

• Integration keys with the Connect this store button beside it (the usual one): one press creates or reuses an API integration named "Zeronode" in this Magento (System > Integrations) with read access to the catalogue and stock, fills the four fields with it and connects the assistant in the same step. Nothing to paste, and nothing is left behind half-done.
• Integration keys filled by hand: store address plus the four values of an integration that already exists.
• Access token: store address plus a bearer token, then Save.

Disconnect removes that integration from this Magento again, together with its consumer and access token, so no unused catalogue access stays behind.

The last two are for a catalogue whose REST root is somewhere else (a separate API domain, a headless setup) or an integration that already exists. Use {store} in the address where the store view code belongs, e.g. https://shop.example/rest/{store}/V1. Keys are sent to Zeronode with the Save and are not stored in Magento.

Disconnecting takes the keys back; the catalogue settings kept in Zeronode (field mapping, tax, price display, store scopes) stay and come back on the next connect.

Content Security Policy

etc/csp_whitelist.xml allows the widget script (content.zeronode.ai), the chat connection (api.zeronode.ai, wss) and the widget's stylesheet. Images are not listed: product photos come from the store's own media. If your product images or the assistant picture are served from another host (a CDN), add it to your own CSP whitelist so the widget can show them.

How the store actions work

The page loads the widget and mounts it with page-side handlers (view/frontend/web/js/widget.js). The handlers call this module's own controllers with the visitor's session and form key:

• POST /zeronode/cart/add (sku, qty): adds a simple/virtual product to the visitor's quote. A product that needs options (configurable, bundle, grouped) is not guessed: the visitor is sent to its page instead.
• POST /zeronode/cart/coupon (code): applies a coupon to the quote.
• GET /zeronode/product/url?sku=: the product's store-view URL.

Nothing customer-specific is rendered into the page, so full page cache stays effective.

The corresponding tool definitions (what the assistant is allowed to call) live in the agent's configuration in the Zeronode admin under Frontend tools: addToCart, openProductPage, openCart, applyCoupon.

Publishing (Packagist)

The repository root is the module root (this file's folder). To release:

git tag v1.0.0 && git push --tags

Packagist reads versions from tags. First-time: register the zeronode vendor on packagist.org and submit the repository URL; a GitHub/Bitbucket webhook keeps it updated.

Local development

In a docker-magento project, mount the module as a Composer path repository:

mkdir -p src/packages && cp -R <this folder> src/packages/zeronode-module-web-agent
bin/clinotty composer config repositories.zeronode-local path packages/zeronode-module-web-agent
bin/clinotty composer require zeronode/module-web-agent:@dev
bin/magento module:enable Zeronode_WebAgent && bin/magento setup:upgrade