vox-cart

The open source voice commerce widget. Browser-native speech recognition, on-device AI voice responses, works on any storefront.

No cloud ASR. No backend required for basic use. Drop in two script tags.

What it does

• Voice search — customer taps a mic button and speaks naturally ("I want honey", "something for Diwali", "ingredients for biryani")
• Smart search pipeline — exact match → category graph → Fuse.js fuzzy → phonetic → context-aware fallback
• On-device TTS — responses spoken back using Supertonic TTS (ONNX, runs via WebGPU or WASM — no cloud), falls back to window.speechSynthesis
• Cart integration — built-in adapters for Shopify, WooCommerce, Odoo, or any custom cart
• Works on any storefront — Shopify, WooCommerce, Odoo, React, plain HTML

Quick start

Paste before </body> on any page:

<script>
  window.VA_CONFIG = {
    productsUrl: 'https://your-server.com/customer/va_xxx.../products',
    cartMode:    'shopify',  // 'shopify' | 'woo' | 'odoo' | 'custom'
  };
</script>
<script src="https://cdn.vox-cart.com/va-search.js" defer></script>
<script src="https://cdn.vox-cart.com/voice-agent.js" defer></script>

The mic button appears bottom-right. That's it.

Search

Search runs client-side via Fuse.js by default — no backend needed. Set useTypesense: false (or omit it) to keep everything local.

To enable server-side Typesense search, set useTypesense: true. The widget will automatically derive the search endpoint from productsUrl (replaces /products with /search) and proxy requests through voice-agent-server:

window.VA_CONFIG = {
  productsUrl:  'https://your-server.com/customer/va_xxx.../products',
  useTypesense: true,
  cartMode:     'shopify',
};

Managed backend (voice-agent-server)

voice-agent-server handles product ingestion, Typesense collection management, and search proxying. It supports Excel, Shopify, and WooCommerce catalogues.

• Admin UI: http://your-server:8002/ui
• Ingest via Excel upload, Shopify API sync, or WooCommerce API sync
• One licence key per customer — passed in the productsUrl path

Product data format

productsUrl must return a JSON array. Each product:

{
  "variant_id":      "123",
  "title":           "Organic Toor Dal 1kg",
  "price":           "₹120",
  "image_url":       "https://...",
  "tag2":            "Pulses & Lentils",
  "tag3":            ["Toor Dal", "Arhar Dal"],
  "tag6":            "Organic",
  "tag7":            "Vegan",
  "tag8":            "Dal / Curry Cooking",
  "tag9":            "1.0 KG",
  "search_keywords": ["arhar", "yellow lentil"],
  "search_tags":     ["dal", "protein"]
}

Important: tag3 must be an array of clean separate strings — not a single pipe-joined string. voice-agent-server's Excel loader splits on |, ,, and ; automatically.

| Field | Required | Description | |---|---|---| | variant_id | Yes | Unique identifier | | title | Yes | Product name | | price | No | Display price (e.g. ₹120, $5.99) | | image_url | No | Full URL to product image | | tag2 | No | Category | | tag3 | No | Subcategory array (clean separate strings) | | tag6–tag9 | No | Variety, dietary flag, pack size, weight | | search_keywords | No | Extra search terms (defaults to tag3 if omitted) | | search_tags | No | Extra keywords for Typesense indexing |

Cart modes

| cartMode | What it calls | |---|---| | odoo | /shop/cart/update_json (Odoo JSON-RPC) | | shopify | /cart/add.js | | woo | /?wc-ajax=add_to_cart | | custom | VA_CONFIG.cartHandler(items) — your own function |

// Custom cart example
window.VA_CONFIG = {
  cartMode:    'custom',
  cartHandler: async function(items) {
    await fetch('/api/cart', {
      method: 'POST',
      body:   JSON.stringify({ items }),
    });
  },
};

VA_CONFIG reference

| Field | Default | Description | |---|---|---| | productsUrl | /voice-agent/products | Product list JSON endpoint | | useTypesense | false | Set true to enable server-side Typesense search via proxy | | logUrl | /voice-agent/log | Client error beacon (optional) | | cartMode | 'odoo' | Cart adapter to use | | cartUrl | platform default | Override default cart endpoint | | cartHandler | — | async (items) => void — required when cartMode='custom' |

TTS models

The on-device TTS uses Supertonic ONNX models (~250MB). Not included in this repo due to size. Download from HuggingFace (onnx-community/Supertonic-TTS-ONNX) and serve from your own CDN or server at /voice-agent/models/onnx-community/Supertonic-TTS-ONNX/.

Falls back to window.speechSynthesis (browser built-in) if models are unavailable — the widget still works fully without them.

Browser support

Requires SpeechRecognition API — supported in Chrome, Edge, and Safari 14.1+. Firefox not supported (no SpeechRecognition implementation).

WebGPU TTS requires Chrome 113+ or Edge 113+. Falls back to WASM on older browsers, falls back to speechSynthesis if WASM fails.

License

MIT