Skip to main content
Version: next

Laravel Server Sync

monoverse/voicebot-laravel-sync is a Composer package that pushes your Laravel catalog and content to VoiceBot so the assistant can answer about your real products, categories and pages.

It is a producer client for the VoiceBot canonical signed-ingest contract: it pairs once, sends a full snapshot to establish a baseline, then streams small incremental deltas as your data changes. Everything runs server-to-server over an HMAC-signed HTTP protocol — no browser, no end-user involvement, no LLM SDK on your side. Voice and retrieval stay on the VoiceBot backend.

Signed, server-to-server

HMAC-SHA256 over https only. No browser, no end-user involvement, no LLM SDK on your side.

Incremental by default

One full snapshot for the baseline, then small per-kind deltas as your Eloquent rows change.

Maps to your schema

A small column map per entity kind in config — or a custom EntitySource when you need full control.

Data channel — your Laravel app to VoiceBot ingest
┌──────────────────┐   gzip-NDJSON snapshot      ┌──────────────┐
│  Your Laravel app│   + signed /events deltas    │  VoiceBot    │
│  + this package  │ ───────────────────────────▶ │  ingest      │
│  (Eloquent →     │   HMAC-SHA256, https only     │  (catalog,   │
│   canonical)     │                               │   RAG)       │
└──────────────────┘                               └──────────────┘

The lifecycle at a glance​

Four steps from an empty connection to a self-maintaining feed:

  1. Step 1pairOne-time handshake mints your tenant id + encrypted shared secret.
  2. Step 2mapPoint each entity kind at an Eloquent model in config/voicebot.php.
  3. Step 3sync --fullPush a complete baseline snapshot of every enabled kind.
  4. Step 4scheduleDeltas every few minutes + a nightly full to reconcile deletes.

Two channels, two keys​

VoiceBot reads your store over two independent channels. Do not confuse them — they use different credentials and flow in opposite directions.

Data channel (this package)Widget channel (browser)
DirectionYour server → VoiceBot (push)End-user browser ↔ VoiceBot (live)
CredentialHMAC shared secret (per-tenant, secret)Publishable key pk_… (public, embeddable)
Obtained viaphp artisan voicebot:pair <code>Copied from the cabinet, dropped in a <script>
CarriesCatalog + content snapshots and deltasVoice/text conversation traffic
TrustSecret, encrypted at rest, never loggedPublic identifier, safe to ship in markup

The data channel feeds the assistant's knowledge; the widget channel is how customers talk to it. This section documents only the data channel. The shared secret minted by pairing is stored encrypted (keyed by your app's APP_KEY) and is never printed, logged, or returned in any command output.

One VoiceBot key, two faces

A tenant has a single VoiceBot identity. The shared secret signs server ingest (this package); the publishable key authorizes the browser widget. Pairing here does not expose or replace your widget key, and the widget key cannot sign ingest.

How it differs from the widget​

The browser widget answers questions using catalog data; this package is what delivers that catalog data in the first place. If your products only exist in your Laravel database, the widget has nothing to talk about until a sync runs. Think of this package as the data pipe and the widget as the microphone.

When to use it​

Use this package when:

  • Your storefront runs on Laravel (any Eloquent-backed catalog — custom shop, a headless backend, a Laravel + Filament admin, etc.).
  • You want the assistant to answer about live products, prices, stock, categories and pages.
  • You can run artisan commands on a schedule (a one-line cron entry).

You do not need this package if your store runs on WooCommerce/WordPress (use the WordPress sync plugin instead) or on another platform with its own VoiceBot producer.

What it sends​

The package maps your Eloquent models to VoiceBot's canonical entity schema and emits the kinds you enable — products, categories, pages and more. You declare the mapping in a config file (a small column map per kind), or bind a fully custom source for anything the map can't express. See Data reference for the entity kinds and required fields, and Mapping for how to wire your models.

The five-minute path​

  1. Install — composer require, publish config, migrate, pair, run doctor.
  2. Map your models in config/voicebot.php.
  3. Push a baseline: php artisan voicebot:sync --full.
  4. Schedule deltas + a nightly full.
  5. Watch operations — exit codes, the dead-letter table, troubleshooting.

Requirements​

  • PHP 8.2+ (Laravel 13 requires PHP 8.3+)
  • Laravel 10, 11, 12 or 13
  • An APP_KEY (used to encrypt the stored shared secret)
  • A reachable VoiceBot ingest endpoint over https (localhost is allowed for local dev)