VoiceBot SDK

VoiceBot puts an AI store assistant on every surface you ship — your website, your native mobile apps — speaking and typing in your customers' language, grounded in your real catalog. A customer taps a launcher, talks or types, and the bot searches your products, opens pages, applies filters, and adds to the cart through handlers you control.

Integration is stack-agnostic: any backend can push the catalog, any frontend can mount the widget, and the assistant's language is a per-store setting — the same product works for a Shopify-style storefront, a custom Django shop, or a React Native app.

Pick your path

There are three integration paths. They are independent and compose freely — most stores wire the first two and are live; mobile is optional.

1. Backend — get your catalog in

A server-to-server push of your products, categories, and pages so the assistant answers from real data. Pick the producer that matches your stack:

• Node.js — @monoverse/voicebot-node (npm)
• Python — monoverse-voicebot (install from source; PyPI release in progress)
• PHP / Laravel — monoverse/voicebot-laravel-sync (Packagist)
• Any other backend — a custom producer against the signed ingest protocol
• No backend to run? The WordPress/WooCommerce plugin or the managed crawler

Start at Backend — get your catalog in.

2. Frontend — add the widget

The talking widget your end users see on your website — one component (or one script tag), one publishable pk_ key:

• Vanilla JS — a single <script> tag, no package
• React — @monoverse/voicebot-react
• Vue — @monoverse/voicebot-vue
• Next.js — @monoverse/voicebot-next

Start at Frontend — add the widget.

3. Mobile — the assistant inside your app

The same assistant in a native app via a headless SDK — you own the UI and the tool handlers:

• React Native — @monoverse/voicebot-react-native (npm)
• Flutter — voicebot_flutter (pub.dev)

Start at the Quickstart — mobile path.

Running a custom storefront?

Custom site integration is the end-to-end map for custom sites — a backend × frontend stack matrix covering the capability grant (host_profile), the cart/variant bridge, and confirmation behavior.

New to the architecture? Read Architecture and Tenant isolation first. Wondering which credential goes where? See API keys.

What it is

• Voice + text in one session. Realtime microphone streaming (PCM16) and text turns share a single WebSocket.
• One assistant, every surface. The web widget and the mobile SDKs are behaviorally identical — same lifecycle, same wire protocol, same bot.
• Grounded in your data. The bot answers from the catalog and content your backend ingests — it never guesses prices or stock.
• Your language. The assistant's language is a per-store setting, not a code change.

Architecture

The single most important architectural fact:

The assistant runs 100% server-side. No AI model ships in your page or your app binary.

Clients only do audio/text I/O — they capture input and play or render the bot's output. Everything else (the LLM, retrieval-augmented catalog search, tool execution) stays on the VoiceBot backend, for the web widget and the mobile SDKs alike.

┌──────────────┐   PCM16 16 kHz (up)    ┌──────────────┐   audio/pcm     ┌─────────────┐
│  Your site   │ ─────────────────────▶ │  VoiceBot    │ ──────────────▶ │ Gemini Live │
│  or app      │   raw WebSocket frames │  backend     │   server-side   │ (voice+LLM) │
│ (I/O only)   │ ◀───────────────────── │ (Gemini      │ ◀────────────── │             │
└──────────────┘   PCM16 24 kHz (down)  │  bridge,     │                 └─────────────┘
       │           + JSON control       │  RAG, tools) │
       │                                └──────────────┘
       │ deep links / cart handlers            ▲
       ▼                                       │ signed ingest (HMAC)
  your routes / cart API              your backend (catalog producer)

Native mobile SDKs

The mobile SDKs are headless: they give you a typed client/session state machine and an event stream — drop them behind any component tree. (On the web, the browser widget self-mounts — same assistant, same backend, no wiring.)

• One key for web + app. Your existing VoiceBot key authorizes the mobile app too. See Auth & API keys.
• Two native SDKs, one contract. @monoverse/voicebot-react-native (npm) and voicebot_flutter (pub.dev) speak the same wire protocol.

Why raw WebSocket + PCM16 (not WebRTC)

The transport is a raw WebSocket carrying binary PCM16 frames — the same path the web widget already uses (ADR-049). WebRTC's headline advantage is low-latency peer-to-peer media, but there is no peer-to-peer here: every turn hops device → our backend → Gemini. That mandatory Gemini hop erases the WebRTC latency win, while WebRTC would add SFU/TURN/ICE/DTLS infrastructure for no payoff. Hardware echo cancellation on the device (.voiceChat on iOS, VOICE_COMMUNICATION + AcousticEchoCanceler on Android) covers the echo case WebRTC is often chosen for.

See Audio & permissions for the native audio details.

What the SDK ships

Layer	What it does	Native code?
Headless core	VoicebotClient / VoicebotSession state machine, WebSocket transport (reconnect ≤3, ~25s heartbeat, 60s reattach), protocol codec, tool-handler registry, deep-link map, event streams	No
Text path	sendText → transcript round-trip	No native code at all
Native audio	mic → PCM16 16 kHz → WS; WS → PCM16 24 kHz → speaker; hardware AEC; barge-in flush	Yes (voice only)
Optional UI kit	VoiceButton, ChatPanel — fully replaceable	No

Next steps

• Quickstart — the shortest path for each of the three routes.
• API keys — which credential goes where (pk_, vb_pk_, the ingest secret).
• Backend — get your catalog in — pick a producer.
• Frontend — add the widget — pick a wrapper.
• Custom site integration — the custom-storefront map.
• Wire protocol — the reference contract every client speaks.