Skip to main content
Version: next

Ingest Protocol Reference

This is the language-agnostic source of truth for the VoiceBot signed ingest protocol (v2) — the push-only contract every backend producer speaks to feed a tenant's catalog and content. The Laravel package, the WordPress plugin, and any custom Node/Python producer all implement exactly what's described here.

This is reference, not a prerequisite

You do not need to read this end-to-end to integrate. The per-stack pages (and the shared signing/entity partials they inline) give you a working sync without leaving the page. Come here when you're implementing the protocol yourself or debugging the wire.

Mental model​

A producer does three things, forever:

  1. Pair once — exchange a one-time pair code for a per-tenant HMAC shared secret. After this, every request is signed.
  2. Snapshot — stream the full catalog as gzipped NDJSON to establish a baseline (init → upload → finalize).
  3. Deltas — push small signed /events batches as data changes, plus a periodic full snapshot to reconcile deletes.

Transport is HTTPS only, TLS 1.2+. JSON on the control endpoints; application/x-ndjson (optionally gzipped) on the upload.

The contract in four parts​

PageWhat it covers
Authentication & HMACPairing, the shared secret, the string-to-sign, the required headers, replay protection.
EndpointsThe 7 endpoints, their auth, and idempotency semantics.
EntitiesThe 16 entity kinds, the envelope, and the payload rules (money, slugs, plain text).
ErrorsThe error shape, the status table, and why signed requests aren't blindly retried.

Versioning​

The protocol is at major version 2. The wire header X-VoiceBot-Protocol-Version carries the integer major (2) on every request, including /pair; a mismatch is rejected with 426 Upgrade Required. Minor additions (new optional fields, new entity kinds) do not change the wire integer — producers may send fields a backend hasn't learned yet, and they're ignored rather than rejected.

Ground truth​

This reference mirrors the running backend. When a detail here and the code disagree, the code wins — the canonical sources are the ingest module's auth.py (signing), api.py (endpoints), and parsers/entity_validators.py (entity payloads).

Next​