Skip to content

Python SDK

The official Python SDK for the Uchara Chat Platform.

Installation

pip install uchara-sdk

Requirements

Python 3.8+

Visitor SDK

from uchara import VisitorSDK

visitor = VisitorSDK(
    api_url="https://api.uchara.com",
    widget_token="wgt_your_token",
    contact_metadata={"user_id": "123"},
)

# Initialize session
session = visitor.init()
print(f"Contact ID: {session['contact_id']}")

# Start conversation
conv = visitor.start_conversation(message="Hello!")

# Get messages
messages = visitor.get_messages(conv["id"], limit=50)

# Send message
message = visitor.send_message(conv["id"], content="I need help")

# Real-time events
def on_event(event):
    if event["type"] == "message.new":
        print(f"New message: {event['payload']['content']}")

visitor.connect(on_event=on_event)

Agent SDK

from uchara import AgentSDK, ConversationStatus, Priority

agent = AgentSDK(api_url="https://api.uchara.com")

# Login
agent.login(email="agent@company.com", password="...")

# List conversations
convs = agent.list_conversations(
    status=ConversationStatus.OPEN,
    limit=20,
)

# Send reply
agent.send_message(convs[0]["id"], content="Hi! How can I help?")

# Assign conversation
agent.assign_conversation(conv_id, assigned_to=agent_id)

# Update workflow
agent.update_workflow(
    conv_id,
    status=ConversationStatus.OPEN,
    priority=Priority.HIGH,
)

# Resolve
agent.resolve_conversation(conv_id)

# Real-time events
def on_event(event):
    if event["type"] == "conversation.new":
        print("New conversation!")

agent.connect(on_event=on_event)

Server SDK

from uchara import ServerSDK
import os

server = ServerSDK(
    api_url="https://api.uchara.com",
    api_key=os.getenv("UCHARA_API_KEY"),
)

# Send notification
server.send_message(
    conversation_id="...",
    content="Your order has shipped!",
    sender_type="bot",
)

# Upsert contact
contact = server.upsert_contact(
    external_id="user_123",
    name="John Doe",
    email="john@example.com",
)

# List conversations
conversations = server.list_conversations(
    status=ConversationStatus.OPEN,
)

Error Handling

from uchara import APIError

try:
    agent.send_message(conversation_id, content="Hello")
except APIError as e:
    print(f"HTTP {e.status}: {e.message}")

    if e.status == 401:
        # Token expired
        agent.login(email="...", password="...")
    elif e.status == 429:
        # Rate limited
        pass

Type Hints

The SDK includes full type hints:

from uchara import (
    Message,
    Conversation,
    Contact,
    Member,
    Channel,
    ConversationStatus,
    Priority,
    SenderType,
    ContentType,
)

Async Support

For async applications, run blocking calls in a thread pool:

import asyncio
from uchara import ServerSDK

server = ServerSDK(api_url="...", api_key="...")

async def send_async(conv_id: str, content: str):
    loop = asyncio.get_event_loop()
    return await loop.run_in_executor(
        None,
        lambda: server.send_message(conv_id, content=content)
    )

Resources