bloonio_chat_relay_client

Python SDK for bloonio_chat_relay. Lets a tenant backend integrate the bloonio chat PaaS via the same tenant_id + tenant_secret model that bloonio_auth_relay_client uses for auth.

Install

pip install bloonio-chat-relay-client[fastapi]   # for FastAPI tenants
pip install bloonio-chat-relay-client[django]    # for Django tenants
pip install bloonio-chat-relay-client            # framework-agnostic core only

Two-minute integration (FastAPI)

# .env
BLOONIO_CHAT_BASE_URL=https://chat-relay.example.com
BLOONIO_CHAT_TENANT_ID=<uuid>
BLOONIO_CHAT_TENANT_SECRET=sk_...
BLOONIO_CHAT_CALLBACK_BASE_URL=https://your-backend.example.com

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

app = FastAPI()
BloonioChatAdapter.from_env(app)   # mounts /api/v1/chat-callbacks/* + wires the client

# anywhere
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="Where is my order?")

# For in-app SDKs (web/Flutter) — mint a short-lived signed token your
# client SDK uses to authenticate its WebSocket to chat-relay.
token = chat.mint_visitor_token(
    visitor_user_id="user-123",
    visitor_email_hash="sha256:...",
    ttl_seconds=3600,
)

Public surface

from bloonio_chat_relay_client import (
    ChatRelayClient,         # sync
    AsyncChatRelayClient,    # async
    ChatRelaySettings,
    ChatRelayError,
    # Domain types (Pydantic)
    Conversation,
    Message,
    Ticket,
    KnowledgeDocument,
    WebhookEvent,
    # Enums
    MessageRole,
    ConversationStatus,
    TicketStatus,
    TicketPriority,
    WebhookEventType,
)

Webhook callbacks

The adapter mounts nine HMAC#1-verified endpoints under /api/v1/chat-callbacks/*:

Provide handlers in BloonioChatAdapter.from_env(app, handlers={...}) to react to events on your side. Handlers are optional — events without a registered handler are accepted (HMAC#1 verified), logged at debug, and return {"received": True}.

Agent-takeover event payloads (phase 10a)

The three agent_* events share the same body shape:

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

Use these to update your CRM, send push notifications, or trigger analytics — apps_api's ChatIntegrationService.handle_agent_assigned(...) is the canonical reference handler (phase 10d).

Django

The same nine endpoints as Django urlpatterns — include them under the prefix you registered with the relay:

# urls.py
from django.urls import include, path
from bloonio_chat_relay_client import WebhookEventType
from bloonio_chat_relay_client.adapters.django import build_callback_urlpatterns

def on_message(ev):             # sync or async — both work
    ...

urlpatterns = [
    path(
        "api/v1/chat-callbacks/",
        include(build_callback_urlpatterns(handlers={WebhookEventType.MESSAGE_RECEIVED: on_message})),
    ),
]

settings=None reads BLOONIO_CHAT_* env vars. Semantics mirror the FastAPI router: 401 on missing/bad HMAC#1 headers, 400 on a bad payload or a body whose event_type doesn't match the path, handler exceptions logged but still 200. Outbound calls need no adapter — build ChatRelayClient(ChatRelaySettings()) anywhere.

Relationship to bloonio_auth_relay_client

This SDK is the chat analog of bloonio_auth_relay_client. The HMAC scheme is identical (header names, signature format, replay-protection window), so a backend that already integrates the auth SDK can reuse operator muscle memory. Only the domain types and the wrapped methods differ. See bloonio_chat_api/docs/12_PAAS_CONVERSION_PLAN.md §4.2 / §7.1.

License

Proprietary — Bloonio internal.