Developers: Hooks & Filters

Everything on this page is public API and kept backward compatible between releases. Anything not listed here is internal and may change without notice.

Put these in your theme’s functions.php or a small site plugin. None of them is needed for normal use — the assistant works without a line of code.

Is the Plugin Running?

if ( function_exists( 'ai_shopping_assistant_is_running' ) && ai_shopping_assistant_is_running() ) {
    // The assistants, their tools and their routes are available.
}

This answers the practical question — is there an assistant to integrate with on this request? It is false when the plugin’s requirements are not met, and false without an active license, because a plugin without one registers nothing beyond its own License screen: no tools, no chat on the shop and no REST routes but the license’s own.

Do not test for the plugin by counting ai_shopping_assistant_loaded yourself. That action fires whether or not the license is active, so it would tell you the plugin is there while none of it is available. Use ai_shopping_assistant_is_running().

Actions

Action	When it fires	Arguments
`ai_shopping_assistant_loaded`	After the plugin registers its hooks — including when the license is inactive and all it registered was the License screen	The plugin instance
`ai_shopping_assistant_outcome`	A conversation started, a cart was created, or a shopper was sent to checkout	`string $event`, `float $value`
`ai_shopping_assistant_event`	Every event the plugin records — tool calls, refusals and knowledge denials	The audit event
`ai_shopping_assistant_search_missed`	A product search found nothing	The search text

Every action and filter below the first one fires only while the plugin is running. Without an active license none of them is ever reached, so a listener on them needs no license check of its own.

Search and Language

Filter	Default	What it changes
`ai_shopping_assistant_search_words`	The shopper’s words, filler removed and plurals stemmed	The words a product search tries one at a time. Add your shop’s synonyms here.
`ai_shopping_assistant_retrieval_lexicon`	Word lists for seven languages	The words the no-AI answerer recognises. Add a language, or more words for one. A term ending in `*` matches any ending.

// Treat "jumper" as another word for "hoodie".
add_filter( 'ai_shopping_assistant_search_words', function ( $words ) {
    if ( in_array( 'jumper', $words, true ) ) {
        $words[] = 'hoodie';
    }
    return $words;
} );

Orders and Tracking

Filter	Default	What it changes
`ai_shopping_assistant_order_tracking`	From Advanced Shipment Tracking, WooCommerce Shipment Tracking and TrackShip	The shipments shown to a customer for their own order. Only `provider`, `number`, `shipped`, `link` and `status` survive.
`ai_shopping_assistant_order_id_from_number`	The number, when numeric	Maps a customer-facing order number to an order id. Use this with a sequential order number plugin.
`ai_shopping_assistant_login_url`	The WooCommerce My account page	Where the Log in button sends a guest who asked about an order.

Returns

Filter	Default	What it changes
`ai_shopping_assistant_returns_available`	Whether Returns for WooCommerce is active and licensed	Whether the chat offers its returns form. Return `false` to turn it off.

Where the Chat Appears

Filter	Default	What it changes
`ai_shopping_assistant_shop_widget_enabled`	true	Whether the chat button appears on this request. Use it for a landing page the settings cannot describe.
`ai_shopping_assistant_shop_disclosure`	Per mode	The wording of the line under the message box. It cannot be switched off.
`ai_shopping_assistant_shop_branding`	On	The “powered by” line.

Cost and Rate Limits

Filter	Default	What it changes
`ai_shopping_assistant_daily_tokens`	500,000	The daily token budget. The second argument is the assistant.
`ai_shopping_assistant_message_cap`	20	Messages allowed in one conversation.
`ai_shopping_assistant_shop_max_rounds`	4	Tool rounds for one shopper message.
`ai_shopping_assistant_shop_max_tokens`	15,000	Tokens of tool results for one shopper message.
`ai_shopping_assistant_shop_retrieval_budget`	3,000	Tokens of quoted material per turn. Over it, material is trimmed and the trim is declared.
`ai_shopping_assistant_shop_visitor_per_minute`	20	Messages one address may send per minute.

Privacy and Logging

Filter	Default	What it changes
`ai_shopping_assistant_visitor_ip`	`REMOTE_ADDR`	The address guest limits key on.
`ai_shopping_assistant_event_retention_days`	30	How long the activity log is kept. The daily clear-out pauses while the license is inactive, so nothing is removed during that time.
`ai_shopping_assistant_public_email_addresses`	The site’s admin email	Addresses the chat may repeat to shoppers. Others are masked.

Behind a reverse proxy or CDN, ai_shopping_assistant_visitor_ip should return the client address your proxy sets — never a forwarded header the proxy does not overwrite, which a visitor could set themselves to slip past the limits.

Store Assistant

Filter	Default	What it changes
`ai_shopping_assistant_chat_system_prompt`	The built prompt	The store assistant’s instructions.
`ai_shopping_assistant_chat_max_rounds` / `_max_tokens`	6 / 60,000	Its per-question caps.
`ai_shopping_assistant_seo_description_keys`	Yoast SEO, Rank Math and SEOPress keys	The product meta checked by “products missing an SEO description”.

Detecting the Plugin From Another Plugin

\ZoremAgentBridge\V1\Bridge::features()->has( 'agent-os.experiences' );

This feature is announced only while the plugin is running, so like ai_shopping_assistant_is_running() it is false on a site whose license is inactive. Either check is a safe way to decide whether to integrate.

There is deliberately no filter on an assistant’s tool list. Each assistant’s tools are fixed in the code, so no plugin and no setting can widen what it is able to do.