Seekmodo developer docs

← First-party chat widget · MCP tools · Solutions overview

Build a shopper AI chatbot on Seekmodo

Seekmodo gives you a live, ranked product index and MCP / REST tools so an LLM can recommend real catalog items with storefront URLs — not hallucinated SKUs. This guide covers building a custom storefront agent of production calibre: floating widget, tool-calling loop, Seekmodo for product discovery, optional platform MCP for orders / policy, compiled FAQ knowledge, and clean handoff to human support.

Prefer a drop-in widget with gateway-hosted reasoning? Use <seekmodo-chat> and the chat tool instead — this page is for teams that own the agent loop (OpenAI / Anthropic / etc.) and want Seekmodo as the catalog brain.

1. Two paths — pick deliberately

2. Reference architecture

Shopper floating widget
        │
        ▼
Your chat API (storefront origin)
        │
        ▼
LLM agent loop (OpenAI tools / Anthropic tool_use / …)
        ├── seekmodo_product_search  →  HMAC POST /v1/search  (or MCP search)
        ├── recommend_* (optional)   →  POST /v1/recommend.*
        ├── store_mcp_* (optional)   →  your CMS MCP (orders, coupons, …)
        ├── kb_search (optional)     →  compiled FAQ / policy pages
        └── open_support_ticket      →  email / helpdesk handoff

Production agents that feel “store-native” almost always separate product discovery (Seekmodo) from account / order mutations (your platform MCP) and policy text (compiled knowledge base). The model must not invent prices, tracking numbers, or refund outcomes — those come only from tool results.

3. Seekmodo tools to expose to the LLM

Wire a thin wrapper tool (for example seekmodo_product_search) that calls Seekmodo server-side. Prefer the authenticated REST shim — same bodies as MCP:

• POST /v1/search — primary gift / product discovery (required)
• suggest — short query refinement / typeahead hints (optional)
• recommend.related, recommend.also_bought, recommend.trending — “complete the gift” / browse assists (optional, Growth+ where gated)
• catalog.get — hydrate a known product id after search (optional)

Interactive schemas: Search, Recommendations, full REST OpenAPI, MCP catalog, Sandbox.

4. Do not expose operator tools to shoppers

The storefront chatbot must not call merchandising, LTR, tenant secrets, index / prune, analytics, or admin MCP tools. Those are for merchants and operators. Product discovery for shoppers is read-oriented search / recommend only. See custom connector guide for the broader tool surface.

5. Auth and storefront host

1. Mint tenant_id + shared secret from admin → Settings → Developer.
2. Call Seekmodo from your server (chat API), never from browser JS with the shared secret. Sign HMAC as in /docs/rest or use an SDK.
3. When the tenant has a locked production storefront host, send X-Seekmodo-Storefront-Host matching the shopper’s site (dev / staging hosts must be allowlisted) — see tenant settings.
4. Pass shopper session_id, ua, and ip on search when available so bot-check and learning stay accurate.

6. Wrapper tool shape (agent-facing)

Keep the LLM-facing schema small. Example OpenAI-style function:

{
  "name": "seekmodo_product_search",
  "description": "Search this store's live product catalog. Prefer for gift ideas and product recommendations. Returns name, price, URL, image, short description.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "Shopper intent in natural language or keywords" },
      "limit": { "type": "integer", "minimum": 1, "maximum": 20, "default": 8 }
    },
    "required": ["query"]
  }
}

Server implementation maps to POST /v1/search { "q": query, "per_page": limit } and normalises hits to fields the prompt can cite. On gateway failure, return a structured error (for example seekmodo_unavailable) so the agent escalates instead of inventing products.

Prompt rule: prefer Seekmodo over native SQL catalog search or sitemap fallbacks for recommendations. Fallbacks are for resilience, not primary ranking.

7. Citations and answer rules

• Only recommend products returned by Seekmodo (or your store product detail tool) in this turn — never other retailers or remembered SKUs.
• Always include the storefront product URL from the tool result.
• Prices and stock must come from the payload; say when results look stale or empty.
• Cap results shown to the shopper (for example 3–5) even if the tool returns more.

8. Intent matrix (calibre checklist)

Agents that feel complete cover more than “find a product.” Use this matrix to decide what tools you still need on the store side (Seekmodo does not replace order APIs):

9. Guardrails

• Allowlist tools in code — the model cannot discover operator MCP by name.
• Cap tool calls per turn and messages per conversation (the first-party chat tool uses hard ceilings of 20 sub-calls / turn and 30 messages — match or tighten).
• Verify guest email before opening tickets or contact forms.
• After human handoff, freeze further bot replies on that session so CS owns the thread.
• Log tool names + args (redact PII) for CS audit; do not log the Seekmodo shared secret.

10. Metering and plans

Each Seekmodo search (and other search-bucket tools) counts toward the tenant search quota like a storefront query. The first-party chat path also meters outer chat turns — see the worked example on /docs/chat. Custom agents that only call /v1/search pay per search call; size your plan for expected fan-out (often ~1.5–2 searches per shopper turn).

11. Minimal server loop (pseudocode)

async function handleShopperTurn(messages) {
  const tools = [seekmodoProductSearchTool, /* kb, store MCP, ticket */];
  for (let i = 0; i < MAX_TOOL_ROUNDS; i++) {
    const reply = await llm.chat({ messages, tools });
    if (!reply.tool_calls?.length) return reply.content;
    for (const call of reply.tool_calls) {
      const result = await dispatch(call); // HMAC /v1/search etc.
      messages.push(toolResult(call, result));
    }
  }
  return "Let me connect you with the team…"; // escalate
}

SDKs: /docs/sdk. Custom connectors that also own the storefront HTML should still advertise anonymous MCP for external agents — MCP discovery.

12. Verification checklist

• Guest asks for gift ideas → only real products with your domain URLs.
• Seekmodo down → structured error + escalation; no invented catalog.
• Logged-out order question → login prompt; no cross-account leakage.
• “Speak to a human” → ticket/email with transcript; bot stops.
• Admin usage shows search volume rising with chat traffic.
• Staging host works with X-Seekmodo-Storefront-Host allowlist.

Related

• First-party <seekmodo-chat> + metering
• MCP tool catalog
• REST OpenAPI
• Web Components
• MCP catalog search
• Shopper AI chatbot (solutions)