Démarrage rapide

Vous allez approvisionner un tenant de chat, récupérer ses trois identifiants (tenant_id, tenant_secret, widget_public_key), embarquer le widget sur votre page, puis effectuer un appel backend signé vers le relais.

Ce dont vous avez besoin

• La clé admin du relais (X-Admin-Key) — détenue par l’opérateur de plateforme. En libre-service, vous l’obtenez plutôt depuis la Console, sans clé admin.
• L’URL de base du relais, exportée sous BASE_URL. La valeur publique par défaut documentée est https://chat-relay.bloonio.com ; en local, c’est http://127.0.0.1:7811.
• Environ dix minutes.

Étape 1 — Approvisionner un tenant

Seul tenant_name est requis ; tous les autres champs ont une valeur par défaut. La réponse contient tenant_id, tenant_secret et widget_public_key une seule fois.

cURL

curl $BASE_URL/api/v1/provision/tenant \
  -X POST \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_name": "Demo Boutique",
    "allowed_origins": ["https://shop.demo.com", "app://bloonio_chat_flutter"]
  }'

Runbook (provision-tenant.py)

Le script d’exploitation bash/seeds/provision-tenant.py enveloppe le même appel (stdlib uniquement, secrets imprimés une seule fois) :

python3 bash/seeds/provision-tenant.py \
  --relay-url $BASE_URL \
  --admin-key "$ADMIN_API_KEY" \
  --tenant-name "Demo Boutique" \
  --origin https://shop.demo.com \
  --origin app://bloonio_chat_flutter

Il imprime, prêtes à coller, les variables d’environnement du backend (HMAC#1) et celles du widget / SDK in-app.

Réponse (201) — l’enveloppe data contient :

{
  "status_code": 201,
  "data": {
    "tenant_id": "019e4ae7-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
    "tenant_secret": "sk_...",
    "widget_public_key": "pk_...",
    "tenant_name": "Demo Boutique",
    "rate_limit_per_min": 60,
    "created_at": "2026-06-21T10:00:00Z"
  },
  "message": "Tenant provisioned. Save tenant_secret and widget_public_key now — the secret will not be shown again."
}

Secrets affichés une seule fois

tenant_secret et widget_public_key ne sont jamais renvoyés par la suite. Copiez-les immédiatement dans un coffre à secrets. En cas de perte, il faut faire une rotation (Gestion des tenants).

Étape 2 — Capturer les identifiants

Rangez les valeurs là où elles servent — deux surfaces distinctes :

# Backend du tenant (HMAC#1, ex. .env.* de votre service)
CHAT_RELAY_BASE_URL=$BASE_URL
CHAT_RELAY_TENANT_ID=019e4ae7-1a2b-7c3d-8e4f-5a6b7c8d9e0f
CHAT_RELAY_TENANT_SECRET=sk_...        # SECRET — ne jamais committer

# Widget / SDK in-app (.env public — la clé widget n'est pas secrète)
CHAT_TENANT_ID=019e4ae7-1a2b-7c3d-8e4f-5a6b7c8d9e0f
CHAT_WIDGET_PUBLIC_KEY=pk_...

La widget_public_key n’est pas un secret : elle s’apparie au tenant_id pour router le trafic du widget et vérifier allowed_origins. Le tenant_secret, lui, signe vos appels backend — gardez-le côté serveur.

Étape 3 — Poser le widget

Avec @bloonio/chat-angular, déclarez le fournisseur puis déposez le lanceur n’importe où. Détails complets sur Widget & SDK.

app.config.ts

import { provideBloonioChat } from '@bloonio/chat-angular';

export const appConfig = {
  providers: [
    provideBloonioChat({
      tenantId: '019e4ae7-1a2b-7c3d-8e4f-5a6b7c8d9e0f',
      publicKey: 'pk_...',
      baseUrl: '$BASE_URL',
      locale: 'fr',
    }),
  ],
};

// un composant standalone
import { BloonioChatLauncherComponent } from '@bloonio/chat-angular';

@Component({
  standalone: true,
  imports: [BloonioChatLauncherComponent],
  template: `<router-outlet /> <bloonio-chat-launcher />`,
})
export class AppComponent {}

L’origine de votre page doit figurer dans allowed_origins, sinon le relais refuse la création de session visiteur (403).

Étape 4 — Signer un appel backend

Les appels backend → relais (/api/v1/relay/*) sont signés en HMAC#1. Le SDK Python signe pour vous ; voici l’exemple de l’échange d’un jeton opérateur, où votre backend délègue son identité au relais.

SDK Python

from bloonio_chat_relay_client import get_chat_client

chat = get_chat_client()  # lit BLOONIO_CHAT_* depuis l'environnement
convo = chat.create_conversation(
    visitor_user_id="user-123",
    visitor_display_name="Marie",
    locale="fr",
)
chat.send_message(convo.id, role="visitor", content="Où est ma commande ?")

cURL (en-têtes HMAC#1)

# X-Bloonio-Signature = hex(hmac_sha256(tenant_secret, f"{ts_ms}.{sha256_hex(body)}"))
curl $BASE_URL/api/v1/relay/fetch/operator-token \
  -X POST \
  -H "X-Bloonio-Tenant-Id: 019e4ae7-1a2b-7c3d-8e4f-5a6b7c8d9e0f" \
  -H "X-Bloonio-Timestamp: 1718960000000" \
  -H "X-Bloonio-Signature: <signature>" \
  -H "Content-Type: application/json" \
  -d '{"email": "merchant@acme.com"}'

La recette HMAC complète

Les trois en-têtes (X-Bloonio-Tenant-Id, X-Bloonio-Timestamp, X-Bloonio-Signature), la fenêtre de tolérance d’horloge (~30 s) et la protection anti-rejeu (10 min) sont décrits une seule fois sur la page Authentification. Ne ré-implémentez pas la signature à la main si vous pouvez utiliser le SDK Python.

Ce qui vient de se passer

1. Vous avez approvisionné un tenant avec la clé admin et capturé ses trois identifiants (affichés une seule fois).
2. Le widget s’authentifie auprès du relais avec la widget_public_key + le tenant_id, et crée une session visiteur si l’origine est autorisée.
3. Votre backend signe ses appels en HMAC#1 avec le tenant_secret ; le relais vérifie la signature, la fenêtre temporelle et le statut du tenant avant de router vers bloonio_chat_api.

Étapes suivantes

• Brancher des opérateurs humains. Voir Opérateurs.
• Recevoir les événements sur votre backend. Voir Webhooks.
• Faire tourner ou suspendre un tenant. Voir Gestion des tenants.
• Intégrer en libre-service, sans clé admin. Voir Console.