Architecture

VoiceBot is one backend speaking one wire protocol to every surface. Before you pick a stack, it helps to hold three facts in your head: voice is server-side, your store is a tenant, and there are exactly three planes you can integrate.

Voice runs 100% server-side

The single most important fact:

The LLM, retrieval, and tool execution all run on the VoiceBot backend (Gemini Live). No AI model ships on the device or in the browser.

Every client — a website widget, a native app, a phone call — only does I/O: it captures audio (PCM16) or text and streams it to the backend, then plays back the audio or renders the text the backend returns. Nothing about the model, your catalog, or your secrets lives on the client. This is why the same assistant behaves identically across web, mobile, and telephony, and why a browser publishable key can be shipped in plain markup without leaking anything.

One tenant, one assistant

A merchant is a tenant. A tenant has a single VoiceBot identity that backs everything: the catalog the assistant is grounded in, the widget customers talk to, and any native apps. The tenant owns a small set of credentials, each scoped to one plane — see Tenant isolation for the full model. The rule to remember: the client never asserts which tenant it is; the backend always derives tenant_id from the credential and binds it server-side.

The three planes

Integrating VoiceBot means working on one or both of two axes, plus an optional mobile surface. They compose freely — you don't pick a pair from a grid.

                         ┌───────────────────────────────┐
                         │        VoiceBot backend        │
                         │  Gemini Live · RAG · tools     │
                         │  one tenant model, one protocol│
                         └───────────────────────────────┘
        push (HMAC)        ▲           ▲ live (pk_)        ▲ live (session token)
   ───────────────────────┘           │                   │
   ┌──────────────────┐     ┌─────────┴────────┐  ┌────────┴─────────┐
   │ Backend ingest   │     │ Browser widget   │  │ Native mobile    │
   │ (get catalog in) │     │ (add the widget) │  │ (headless SDK)   │
   │ Laravel/Node/... │     │ React/Vue/Next/  │  │ React Native /   │
   │ or no-code       │     │ Vanilla          │  │ Flutter          │
   └──────────────────┘     └──────────────────┘  └──────────────────┘

Plane 1 — Backend: get your catalog in

A server-to-server push of your products, categories, and pages over the signed ingest protocol. This is what the assistant is grounded in: if your data isn't ingested, the widget has nothing to talk about. Producers exist for Laravel today, with Node and Python following; or use a no-code path (crawler / read-only pull) when you can't run a producer. The contract is documented end-to-end in the Ingest Protocol Reference.

Plane 2 — Frontend: add the widget

The browser widget your end users talk to. You drop one component (or one script tag) with your public key, and the deployed bundle self-mounts. Wrappers exist for React today, with Vue, Next.js, and Vanilla following — see the frontend overview.

Plane 3 — Native mobile

A headless SDK that brings the same assistant into a native app — you own the UI and the tool handlers. Voice still runs server-side; the SDK only does native audio I/O. Start at the mobile quickstart.

Where to go next

• Tenant isolation — the three credentials and what you're responsible for.
• Backend — get your catalog in — pick a producer.
• Frontend — add the widget — pick a framework.