Présentation du Chat Relay

Le Chat Relay est la passerelle multi-tenant du PaaS de chat Bloonio. Il se place entre les widgets de chat, les SDK in-app et les backends locataires d’un côté, et le « cerveau » bloonio_chat_api (RAG, tickets, persistance des conversations) de l’autre.

Votre application devient un tenant du relais. Vous recevez à l’approvisionnement un tenant_id, un tenant_secret (pour signer vos appels backend) et une widget_public_key (à embarquer dans le widget), puis vous branchez le chat sans jamais exposer votre logique métier au relais.

Quand l’utiliser

Le Chat Relay couvre le chat client de bout en bout :

un widget web (Tidio-like) ou un SDK in-app pour vos visiteurs ;
un bot RAG qui répond automatiquement à partir de votre base de connaissances (porté par bloonio_chat_api) ;
une prise en main humaine par des opérateurs, avec des files par boutique / marchand (routing_keys) ;
des tickets créés automatiquement lors d’une escalade ;
des callbacks webhook signés vers votre backend à chaque événement ;
une console libre-service pour que chaque tenant gère ses propres clés, opérateurs et membres.

Architecture

Le flux nominal va du visiteur au backend du tenant, en passant par le relais et le cerveau de chat :

┌──────────────────────────────────────────────────────────────┐
│  chat-widget  ·  @bloonio/chat-angular  ·  SDK in-app        │  côté visiteur
└─────────────────────────────┬────────────────────────────────┘
                              │ clé widget + token visiteur + WebSocket
                              ▼
                  ┌─────────────────────────┐
                  │  bloonio_chat_relay     │  port 7811
                  │  (cette passerelle)     │
                  └─────────────┬───────────┘
                                │ HMAC#2 (secret relais)
                                ▼
                  ┌─────────────────────────┐
                  │  bloonio_chat_api       │  RAG + tickets + voix
                  └─────────────────────────┘
                                ▲
                                │ HMAC#1 (tenant_secret)
                                │
       bloonio_chat_relay_client (SDK Python)
                                │
       ┌────────────────────────┴────────────────────────┐
       │  votre backend (FastAPI / Django / autre)        │  backend locataire
       └─────────────────────────────────────────────────┘

Deux schémas de signature coexistent :

HMAC#1 — entre votre backend et le relais (et dans l’autre sens pour les callbacks webhook). C’est le seul que vous manipulez. La recette complète vit sur la page Authentification.
HMAC#2 — interne, entre le relais et bloonio_chat_api. Vous n’avez jamais à le connaître.

Ce que possède chaque composant

Préoccupation	Propriétaire
Configuration du tenant (origines, branding, quotas, feature flags)	Chat Relay
Émission et rotation des clés (clé widget, secret backend)	Chat Relay
Vérification HMAC#1 sur les appels entrants	Chat Relay
Fan-out WebSocket entre visiteurs et opérateurs	Chat Relay
Suivi d’usage et application des quotas par tenant	Chat Relay
RAG, base de connaissances, persistance, tickets	`bloonio_chat_api`
Infrastructure voix / vidéo (LiveKit)	`bloonio_chat_voice` (auto-hébergé)

Relation avec `bloonio_chat_api`

bloonio_chat_api est le cerveau : il porte le RAG, la base de connaissances, la persistance des conversations et les tickets. Le Chat Relay ne réimplémente rien de tout cela — il route le trafic multi-tenant, applique l’authentification et les quotas, puis délègue au cerveau via HMAC#2. Vous n’appelez jamais bloonio_chat_api directement : le relais est votre unique point d’entrée.

Les deux files : bot vs humain

À la création d’une session visiteur, le champ mode choisit la file :

bot (par défaut) — les messages partent vers l’assistant RAG de bloonio_chat_api jusqu’à ce qu’un événement d’escalade les bascule vers la file humaine ;
human — le premier message crée directement une affectation en attente (WAITING) et le bot n’intervient jamais.

Les opérateurs sont l’équipe qui répond aux conversations. Une liste routing_keys les restreint à certaines files (modèle « file par boutique ») ; sans routing_keys, un opérateur voit toutes les conversations du tenant. Voir Opérateurs.

Carte des flux

Démarrage rapide Approvisionner un tenant, poser le widget, signer un appel.

Gestion des tenants Cycle de vie admin : mise à jour, rotation, suspension.

Opérateurs Provisionner des opérateurs, jeton scoping, files par boutique.

Widget & SDK Session visiteur, WebSocket, SDK Angular et core.

Webhooks Les 9 événements signés et l'adaptateur SDK.

Console Portail libre-service, MFA et console système.

SDK Python ChatRelayClient, adaptateurs FastAPI / Django, types.

Référence API La spécification OpenAPI complète, source faisant autorité.