AI Actions

AI Actions let your Webnav.ai assistant go beyond answering questions — it can perform operations by calling your own backend API: place an order, look up an order, track a shipment, start a refund, and more.

AI Actions is a Pro / Enterprise feature.

How it works

Webnav.ai is an orchestration layer. It never stores your orders or money — it only calls your API and turns the result into a natural-language reply.

Visitor → Widget → Webnav.ai (LLM decides + calls your MCP tool) → Your MCP server → back to visitor

1. The visitor asks something actionable ("Where's my order #1234?").
2. The LLM matches it to a discovered tool (query_logistics) and extracts parameters (order_id: "1234").
3. Webnav.ai calls the tool on your MCP endpoint over JSON-RPC 2.0.
4. Your server returns the data; the LLM replies in natural language, optionally with a structured card.

For write actions (place order, refund), the assistant first shows a confirmation card. Nothing executes until the visitor clicks Confirm.

Setup (merchant dashboard)

AI Actions connect through an MCP (Model Context Protocol) tool server — Webnav.ai discovers and calls your tools dynamically via JSON-RPC 2.0 over HTTP. Go to Dashboard → AI Actions.

1. Connection
   • Switch Mode to MCP and enter your MCP Endpoint (must be HTTPS on a public host in production).
   • Optionally add Auth Headers (e.g. a bearer token) — values are stored encrypted and forwarded on every request.
2. Test Connection
   • Click Test Connection. Webnav.ai probes your endpoint (initialize + tools/list) through its backend and shows the discovered tools with their annotations. Your endpoint is never contacted directly from the browser.
3. Confirm tools
   • Review the pre-selected write tools and add any additional tool names that should require a confirmation card, then Save.

For the full protocol, per-tool field specs, and wire format, see the MCP Integration Guide.

The five standard e-commerce actions

Action	Type	Confirmation	Purpose
list_products	read	no	Return product catalogue (used for SKU validation)
query_order	read	no	Look up an order's status/details
query_logistics	read	no	Track a shipment
create_order	write	yes	Place a new order
create_refund	write	yes	Start a refund request

list_products is used internally before showing a write confirmation card: if the visitor's requested SKU is not in the catalogue, the assistant asks them to pick a real product instead of presenting a confirmation card for an invalid SKU.

To actually implement the tools these call, follow the E-commerce Integration spec and the MCP Integration Guide.

Confirmation flow (write actions)

LLM collects params → Webnav.ai creates a pending action → widget shows Confirm / Cancel
   → visitor clicks Confirm → Webnav.ai executes exactly once → result card

The pending action is single-use and time-limited (10 minutes), bound to the visitor — it cannot be replayed or confirmed by anyone else. This prevents accidental double orders or double refunds.

Identity (user token)

For user-specific actions, your site mints a short-lived user token for the logged-in visitor and gives it to the widget:

<script src="https://widget.webnav.ai/chat-widget.js"
        data-user-token="YOUR_SIGNED_USER_TOKEN"></script>

Or, in a single-page app, set it after login:

window.WebnavWidget.setUserToken('YOUR_SIGNED_USER_TOKEN');

Webnav.ai does not parse or store this token — it forwards it to your MCP server (configure it as an auth header) so you resolve the real user.

Write tool safety

create_order, create_refund, and any tool whose name starts with create_, refund_, cancel_, or pay_ will always trigger a confirmation card — regardless of what the MCP server's annotations.destructiveHint says. You can also mark additional tools as requiring confirmation in Dashboard → AI Actions → Confirm tools.

See the MCP Integration Guide for full setup, wire format, and the canonical tool specification.

Security & billing notes

• All outbound calls go to your MCP endpoint protected by your auth headers; validate them on your side.
• Outbound hosts must be public (no internal/private addresses — SSRF protection). Dashboard "Test Connection" is always proxied through Webnav.ai — your endpoint is never contacted directly from the browser.
• Every action call is logged (with sensitive fields redacted) — see Dashboard → AI Actions → Call Logs.
• Tool rounds are capped per conversation to control cost.