Herald Documentation
Herald is a real-time event layer with built-in authorization, event replay, and optional chat and presence engines. Connect over WebSocket for live events. Manage streams and members over HTTP.
Sections
Quickstart
Create an account, get an API key, and send your first event.
Architecture
Fan-out model, storage, connection lifecycle, presence, and integration patterns.
WebSocket Protocol
Frame envelope, message types, auth, reconnect, and ack mode.
HTTP API
Stream, member, event, and presence management endpoints.
SDKs
Browser WebSocket SDK, React hooks, and admin SDKs for six languages.
Configuration
Webhooks, token settings, and account configuration.
Self-Hosted
Run Herald on your own infrastructure with Docker.
Engines
The core transport (streams, events, subscribe, replay, auth) is always available. Chat and presence are optional engines you enable per-account.
| Engine | Adds |
|---|---|
| Transport (always on) | Publish, subscribe, catch-up replay, ack mode, ephemeral events, stream/member CRUD, multi-tenant, connection-derived presence |
| Chat | Event edit/delete, reactions, read cursors, typing indicators, user blocking |
| Presence | Manual overrides (away/dnd/offline), per-override expiry, watchlist, batch queries |
How Herald fits
Herald is a delivery layer, not a database. Events are buffered with a configurable retention window (default 7 days) for reconnect replay. Within the buffer, Herald is authoritative for deltas. Beyond it, your app database is the source of truth.
The integration pattern: your app writes to its own database, then publishes through Herald for real-time delivery. Herald mirrors every event back via webhook for reconciliation.