Chat Relay overview
The Chat Relay is the multi-tenant gateway of the Bloonio chat PaaS.
It sits between chat widgets, in-app SDKs and tenant backends on one side,
and the bloonio_chat_api “brain” (RAG, tickets, conversation
persistence) on the other.
Your application becomes a tenant of the relay. At provisioning you
receive a tenant_id, a tenant_secret (to sign your backend calls) and a
widget_public_key (to embed in the widget), then you wire up chat without
ever exposing your business logic to the relay.
When to use it
Section titled “When to use it”The Chat Relay covers customer chat end to end:
- a web widget (Tidio-like) or an in-app SDK for your visitors;
- a RAG bot that answers automatically from your knowledge base
(powered by
bloonio_chat_api); - human takeover by operators, with per-store / per-merchant queues
(
routing_keys); - tickets created automatically on escalation;
- signed webhook callbacks to your backend on every event;
- a self-service console so each tenant manages its own keys, operators and members.
Architecture
Section titled “Architecture”The nominal flow runs from the visitor to the tenant backend, passing through the relay and the chat brain:
┌──────────────────────────────────────────────────────────────┐│ chat-widget · @bloonio/chat-angular · in-app SDK │ visitor side└─────────────────────────────┬────────────────────────────────┘ │ widget key + visitor token + WebSocket ▼ ┌─────────────────────────┐ │ bloonio_chat_relay │ port 7811 │ (this gateway) │ └─────────────┬───────────┘ │ HMAC#2 (relay secret) ▼ ┌─────────────────────────┐ │ bloonio_chat_api │ RAG + tickets + voice └─────────────────────────┘ ▲ │ HMAC#1 (tenant_secret) │ bloonio_chat_relay_client (Python SDK) │ ┌────────────────────────┴────────────────────────┐ │ your backend (FastAPI / Django / other) │ tenant backend └─────────────────────────────────────────────────┘Two signing schemes coexist:
- HMAC#1 — between your backend and the relay (and in the other direction for webhook callbacks). It is the only one you handle. The full recipe lives on the Authentication page.
- HMAC#2 — internal, between the relay and
bloonio_chat_api. You never need to know it.
What each component owns
Section titled “What each component owns”| Concern | Owner |
|---|---|
| Tenant configuration (origins, branding, quotas, feature flags) | Chat Relay |
| Key issuance and rotation (widget key, backend secret) | Chat Relay |
| HMAC#1 verification on incoming calls | Chat Relay |
| WebSocket fan-out between visitors and operators | Chat Relay |
| Usage tracking and per-tenant quota enforcement | Chat Relay |
| RAG, knowledge base, persistence, tickets | bloonio_chat_api |
| Voice / video infrastructure (LiveKit) | bloonio_chat_voice (self-hosted) |
Relationship with bloonio_chat_api
Section titled “Relationship with bloonio_chat_api”bloonio_chat_api is the brain: it carries the RAG, the knowledge base,
conversation persistence and tickets. The Chat Relay reimplements none of
that — it routes multi-tenant traffic, enforces authentication and
quotas, then delegates to the brain over HMAC#2. You never call
bloonio_chat_api directly: the relay is your single entry point.
The two queues: bot vs human
Section titled “The two queues: bot vs human”When a visitor session is created, the mode field picks the queue:
bot(default) — messages go to thebloonio_chat_apiRAG assistant until an escalation event hands them off to the human queue;human— the first message directly creates a pending assignment (WAITING) and the bot never steps in.
Operators are the team that answers conversations. A routing_keys
list restricts them to certain queues (the “per-store queue” model);
without routing_keys, an operator sees every conversation in the tenant.
See Operators.