Python SDK

bloonio_chat_relay_client is the Python SDK for bloonio_chat_relay. It lets a tenant backend integrate the chat PaaS through the same tenant_id + tenant_secret model as the auth SDK — it signs HMAC#1 calls for you and ships ready-to-use adapters.

Analogous to the auth SDK

The HMAC scheme is identical to that of bloonio_auth_relay_client (same headers, same signature format, same replay window). A backend that already integrates the auth SDK reuses the same habits; only the business types and the methods differ.

Installation

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

Configuration (ChatRelaySettings)

The SDK reads the BLOONIO_CHAT_* variables from the environment. Set them in your environment file:

BLOONIO_CHAT_BASE_URL=$BASE_URL
BLOONIO_CHAT_TENANT_ID=019e4ae7-1a2b-7c3d-8e4f-5a6b7c8d9e0f
BLOONIO_CHAT_TENANT_SECRET=sk_...               # SECRET — server-side only
BLOONIO_CHAT_CALLBACK_BASE_URL=https://your-backend.example.com

Never expose the tenant_secret

The tenant_secret signs your HMAC#1 calls; it stays strictly server-side. Only the widget_public_key is meant for the browser (Widget & SDK).

FastAPI

BloonioChatAdapter.from_env(app) mounts the webhook callbacks (/api/v1/chat-callbacks/*, verified with HMAC#1) and wires the client. For async calls, use AsyncChatRelayClient.

main.py

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

app = FastAPI()
BloonioChatAdapter.from_env(app)   # callbacks + wired 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="Mary",
    locale="en",
    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 that your
# client SDK uses to authenticate its WebSocket.
token = chat.mint_visitor_token(
    visitor_user_id="user-123",
    visitor_email_hash="sha256:...",
    ttl_seconds=3600,
)

See Webhooks to register event handlers on the adapter.

Django

For a Django backend, use the synchronous ChatRelayClient client (the [django] extra).

from bloonio_chat_relay_client import get_chat_client

chat = get_chat_client()   # ChatRelayClient — reads BLOONIO_CHAT_* from settings/env
convo = chat.create_conversation(
    visitor_user_id="user-123",
    visitor_display_name="Mary",
    locale="en",
)
chat.send_message(convo.id, role="visitor", content="Where is my order?")

The public surface

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

Item	Role
ChatRelayClient / AsyncChatRelayClient	Synchronous / asynchronous client (HMAC#1 signing included)
ChatRelaySettings	Configuration read from BLOONIO_CHAT_*
Conversation, Message, Ticket, KnowledgeDocument	Pydantic business types
MessageRole, ConversationStatus, TicketStatus, TicketPriority	Enums
ChatRelayError	Root SDK error

Webhook callbacks

The adapter mounts nine HMAC#1 endpoints under /api/v1/chat-callbacks/* (conversation-started, message-received, ticket-created, ticket-assigned, ticket-resolved, escalation-triggered, agent-assigned, agent-released, agent-resolved). Provide your handlers via BloonioChatAdapter.from_env(app, handlers={...}); events with no handler are accepted, logged and return {"received": true}. Full details on Webhooks.

Next steps

• Wire up incoming events. See Webhooks.
• The HMAC#1 signing recipe. See Authentication.
• Provision operators from the backend. See Operators.
• The full REST surface. See the API reference.