Aller au contenu
Bloonio Relay

SDK Python

bloonio_chat_relay_client est le SDK Python de bloonio_chat_relay. Il laisse un backend locataire intégrer le PaaS de chat via le même modèle tenant_id + tenant_secret que le SDK d’auth — il signe les appels HMAC#1 pour vous et fournit des adaptateurs prêts à l’emploi.

Installation

Section intitulée « Installation »
Fenêtre de terminal
pip install bloonio-chat-relay-client[fastapi]   # backends FastAPI
pip install bloonio-chat-relay-client[django]    # backends Django
pip install bloonio-chat-relay-client            # cœur agnostique du framework

Configuration (ChatRelaySettings)

Section intitulée « Configuration (ChatRelaySettings) »

Le SDK lit les variables BLOONIO_CHAT_* de l’environnement. Posez-les dans votre fichier d’environnement :

Fenêtre de terminal
BLOONIO_CHAT_BASE_URL=$BASE_URL
BLOONIO_CHAT_TENANT_ID=019e4ae7-1a2b-7c3d-8e4f-5a6b7c8d9e0f
BLOONIO_CHAT_TENANT_SECRET=sk_...               # SECRET — côté serveur uniquement
BLOONIO_CHAT_CALLBACK_BASE_URL=https://your-backend.example.com

FastAPI

Section intitulée « FastAPI »

BloonioChatAdapter.from_env(app) monte les callbacks webhook (/api/v1/chat-callbacks/*, vérifiés en HMAC#1) et câble le client. Pour les appels asynchrones, utilisez AsyncChatRelayClient.

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


app = FastAPI()
BloonioChatAdapter.from_env(app)   # callbacks + client câblé
# n'importe où
from bloonio_chat_relay_client import get_chat_client


chat = get_chat_client()
convo = chat.create_conversation(
    visitor_user_id="user-123",
    visitor_display_name="Marie",
    locale="fr",
    metadata={"order_id": "ORD-9981"},
)
chat.send_message(convo.id, role="visitor", content="Où est ma commande ?")


# Pour les SDK in-app (web/Flutter) — frapper un jeton signé de courte
# durée que votre SDK client utilise pour authentifier son WebSocket.
token = chat.mint_visitor_token(
    visitor_user_id="user-123",
    visitor_email_hash="sha256:...",
    ttl_seconds=3600,
)

Voir Webhooks pour brancher des handlers d’événements sur l’adaptateur.

Django

Section intitulée « Django »

Pour un backend Django, utilisez le client synchrone ChatRelayClient (extra [django]).

from bloonio_chat_relay_client import get_chat_client


chat = get_chat_client()   # ChatRelayClient — lit BLOONIO_CHAT_* depuis settings/env
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 ?")

La surface publique

Section intitulée « La surface publique »
from bloonio_chat_relay_client import (
    ChatRelayClient,         # synchrone
    AsyncChatRelayClient,    # asynchrone
    ChatRelaySettings,
    ChatRelayError,
    # Types métier (Pydantic)
    Conversation,
    Message,
    Ticket,
    KnowledgeDocument,
    WebhookEvent,
    # Énumérations
    MessageRole,
    ConversationStatus,
    TicketStatus,
    TicketPriority,
    WebhookEventType,
)
ÉlémentRôle
ChatRelayClient / AsyncChatRelayClientClient synchrone / asynchrone (signature HMAC#1 incluse)
ChatRelaySettingsConfiguration lue depuis BLOONIO_CHAT_*
Conversation, Message, Ticket, KnowledgeDocumentTypes métier Pydantic
MessageRole, ConversationStatus, TicketStatus, TicketPriorityÉnumérations
ChatRelayErrorErreur racine du SDK

Callbacks webhook

Section intitulée « Callbacks webhook »

L’adaptateur monte neuf endpoints HMAC#1 sous /api/v1/chat-callbacks/* (conversation-started, message-received, ticket-created, ticket-assigned, ticket-resolved, escalation-triggered, agent-assigned, agent-released, agent-resolved). Fournissez vos handlers via BloonioChatAdapter.from_env(app, handlers={...}) ; les événements sans handler sont acceptés, journalisés et renvoient {"received": true}. Détails complets sur Webhooks.

Étapes suivantes

Section intitulée « Étapes suivantes »