Webhooks

Le relais POSTe les événements de chat vers votre backend sous /api/v1/chat-callbacks/*, chacun signé en HMAC#1 — la même recette que vos appels sortants, dans l’autre sens. L’adaptateur du SDK Python monte ces endpoints et vérifie la signature pour vous.

Où atterrissent les callbacks

Le relais construit l’URL de callback à partir du callback_url_base du tenant (configuré à l’approvisionnement ou via update/tenant) : il y appose /chat-callbacks/<événement> et signe chaque requête.

POST  {callback_url_base}/api/v1/chat-callbacks/<événement>

Vérifiez toujours la signature

Chaque callback porte les en-têtes HMAC#1 (X-Bloonio-Tenant-Id, X-Bloonio-Timestamp, X-Bloonio-Signature). Rejetez toute requête dont la signature ne correspond pas à votre tenant_secret. La recette complète (en-têtes, tolérance d’horloge, anti-rejeu) est sur la page Webhooks & callbacks, et la mécanique de signature sur Authentification.

Les 9 événements

L’adaptateur monte neuf endpoints. Six existent depuis la première phase ; les trois événements agent_* arrivent avec la prise en main par agent.

Chemin	Événement
POST /api/v1/chat-callbacks/conversation-started	Nouvelle conversation ouverte
POST /api/v1/chat-callbacks/message-received	Le visiteur a envoyé un message
POST /api/v1/chat-callbacks/ticket-created	Ticket créé automatiquement par escalade
POST /api/v1/chat-callbacks/ticket-assigned	Ticket pris par un agent humain
POST /api/v1/chat-callbacks/ticket-resolved	Ticket marqué résolu
POST /api/v1/chat-callbacks/escalation-triggered	Le bot a escaladé vers un humain
POST /api/v1/chat-callbacks/agent-assigned	Un opérateur a pris la conversation
POST /api/v1/chat-callbacks/agent-released	L’opérateur a rendu la conversation à la file
POST /api/v1/chat-callbacks/agent-resolved	L’opérateur a marqué la conversation résolue

Monter l’adaptateur (FastAPI)

BloonioChatAdapter.from_env(app) monte les neuf endpoints et câble le client à partir des variables BLOONIO_CHAT_*.

from fastapi import FastAPI
from bloonio_chat_relay_client.adapters.fastapi import BloonioChatAdapter

app = FastAPI()
BloonioChatAdapter.from_env(app)   # monte /api/v1/chat-callbacks/* + câble le client

Branchez des handlers pour réagir aux événements de votre côté. Les handlers sont optionnels : un événement sans handler enregistré est quand même accepté (signature HMAC#1 vérifiée), journalisé en debug, et renvoie {"received": true}.

async def on_ticket_created(event):
    ...  # mettre à jour votre CRM, notifier, etc.

BloonioChatAdapter.from_env(app, handlers={
    "ticket-created": on_ticket_created,
})

Forme des événements agent_*

Les trois événements de prise en main par agent partagent la même forme de corps :

{
  "conversation_id": "<ObjectId chat_api>",
  "tenant_id": "<UUID v7>",
  "status": "ASSIGNED" | "WAITING" | "RESOLVED",
  "operator_id": "<UUID v7>",
  "operator_display_name": "Sarah Chen",   // uniquement sur agent-assigned
  "visitor_session_id": "vs_<base64url>",
  "escalation_reason": "user_requested" | "restricted_topic" | "low_confidence" | "direct" | null,
  "claim_count": 1,
  "claimed_at":  "2026-05-22T12:34:56Z",
  "released_at": null,
  "resolved_at": null
}

Servez-vous-en pour mettre à jour votre CRM, envoyer des notifications push ou déclencher de l’analytique.

Vérification HMAC

1. Lisez les trois en-têtes X-Bloonio-* de la requête entrante.
2. Recalculez hex(hmac_sha256(tenant_secret, f"{ts_ms}.{sha256_hex(body)}")).
3. Comparez en temps constant ; vérifiez la fraîcheur du timestamp et l’absence de rejeu.
4. Si tout passe, traitez l’événement ; sinon, répondez 401.

L’adaptateur du SDK fait exactement cela avant d’appeler vos handlers — préférez-le à une vérification maison.

Étapes suivantes

• Installer et configurer le SDK. Voir SDK Python.
• La recette de signature partagée. Voir Authentification.
• Le contrat générique des callbacks. Voir Webhooks & callbacks.