Quick Start

Choose Your SDK

Uchara provides three types of SDKs for different use cases:

1. 🎨 Visitor SDK

For: Embedding chat widget in your customer-facing app
Platforms: Web, iOS, Android, Flutter, React Native
Auth: Widget token (public)

2. 👤 Agent SDK

For: Building custom agent dashboards
Platforms: Web, iOS, Android, Desktop
Auth: Email/password (JWT)

3. 🔧 Server SDK

For: Backend-to-backend integration
Platforms: Python, Go, PHP, Ruby, Java, .NET, Node.js
Auth: API key (secret)

---

Installation

TypeScript/JavaScript

npm install @uchara/sdk

Python

pip install uchara-sdk

Go

go get github.com/Uchara-AI/sdk-go

iOS (Swift)

Package.swift

dependencies: [
    .package(url: "https://github.com/Uchara-AI/sdk-ios.git", from: "1.0.0")
]

Android (Kotlin)

build.gradle

dependencies {
    implementation("com.uchara:sdk-android:1.0.0")
}

Flutter

pubspec.yaml

dependencies:
  uchara_sdk: ^1.0.0

---

Quick Examples

Visitor SDK (Embed Chat)

TypeScript:

import { VisitorSDK } from '@uchara/sdk/visitor';

const visitor = new VisitorSDK({
  apiURL: 'https://api.uchara.com',
  widgetToken: 'wgt_your_token_here',
});

// Initialize
await visitor.init();

// Start conversation
const conv = await visitor.startConversation({
  message: 'Hello, I need help!',
});

// Listen for messages
visitor.on('message.new', (event) => {
  console.log('New message:', event.payload.content);
});

// Send message
await visitor.sendMessage(conv.id, {
  content: 'Thank you!',
});

Python:

from uchara import VisitorSDK

visitor = VisitorSDK(
    api_url="https://api.uchara.com",
    widget_token="wgt_your_token_here",
)

# Initialize
visitor.init()

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

# Send message
visitor.send_message(conv["id"], content="Thank you!")

---

Agent SDK (Custom Dashboard)

TypeScript:

import { AgentSDK } from '@uchara/sdk/agent';

const agent = new AgentSDK({
  apiURL: 'https://api.uchara.com',
});

// Login
await agent.login({
  email: 'agent@company.com',
  password: 'your_password',
});

// List open conversations
const conversations = await agent.listConversations({
  status: 'open',
});

// Send reply
await agent.sendMessage(conversations[0].id, {
  content: 'Hi! How can I help you today?',
});

// Real-time events
agent.on('conversation.new', (event) => {
  console.log('New conversation:', event.payload);
});

Python:

from uchara import AgentSDK, ConversationStatus

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)

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

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

agent.connect(on_event=on_event)

---

Server SDK (Backend Integration)

TypeScript:

import { ServerSDK } from '@uchara/sdk/server';

const server = new ServerSDK({
  apiURL: 'https://api.uchara.com',
  apiKey: process.env.UCHARA_API_KEY,
});

// Send notification from your backend
await server.sendMessage('conversation_id', {
  content: 'Your order #12345 has shipped! 🚚',
  sender_type: 'bot',
});

Python:

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",
)

Go:

package main

import (
    "context"
    "os"
    "github.com/Uchara-AI/sdk-go"
)

func main() {
    client := uchara.NewServerSDK(uchara.ServerConfig{
        APIURL: "https://api.uchara.com",
        APIKey: os.Getenv("UCHARA_API_KEY"),
    })

    _, err := client.SendMessage(context.Background(), "conv_id", uchara.SendMessageRequest{
        Content:    "Your order has shipped!",
        SenderType: "bot",
    })
}

---

Common Use Cases

1. E-commerce: Order Status Updates

# When order status changes in your system
server.send_message(
    conversation_id=order.conversation_id,
    content=f"🎉 Your order #{order.id} is now {order.status}!",
    sender_type="bot",
)

2. SaaS: In-app Support Chat

// Embed in your React app
function SupportChat() {
  const [sdk] = useState(() => new VisitorSDK({
    apiURL: 'https://api.uchara.com',
    widgetToken: 'wgt_...',
    contactMetadata: {
      user_id: currentUser.id,
      email: currentUser.email,
      plan: currentUser.plan,
    },
  }));

  useEffect(() => {
    sdk.init().then(() => sdk.connect());
    return () => sdk.disconnect();
  }, []);

  // ... render chat UI
}

3. Mobile App: Customer Support

// iOS Swift
import UcharaSDK

class ChatViewController: UIViewController {
    let visitor = VisitorSDK(
        apiURL: "https://api.uchara.com",
        widgetToken: "wgt_..."
    )

    override func viewDidLoad() {
        super.viewDidLoad()

        visitor.initialize { result in
            switch result {
            case .success:
                self.loadConversation()
            case .failure(let error):
                print("Error: \(error)")
            }
        }
    }
}

4. Custom Agent Dashboard

# CLI dashboard for agents
import curses
from uchara import AgentSDK

agent = AgentSDK(api_url="https://api.uchara.com")
agent.login(email="agent@company.com", password="...")

def on_event(event):
    if event["type"] == "conversation.new":
        # Show notification
        show_notification(f"New chat from {event['payload']['contact_name']}")

agent.connect(on_event=on_event)

# Display conversations in terminal UI
conversations = agent.list_conversations(status="open")
for conv in conversations:
    print(f"[{conv['id']}] {conv['contact_name']}: {conv['last_message']}")

---

Next Steps

1. Get your credentials:

   • Visitor SDK: Get widget token from channel settings
   • Agent SDK: Use your agent email/password
   • Server SDK: Generate API key in workspace settings (admin only)

2. Read the full documentation:

   • Technical Documentation
   • API Reference
   • Platform-specific guides: https://docs.uchara.com/sdk/

3. Join the community:

   • GitHub: https://github.com/Uchara-AI
   • Discord: https://discord.gg/uchara
   • Email: developers@uchara.com

---

Troubleshooting

”Unauthorized” error

Visitor SDK:

• Check widget token is correct
• Call init() before other methods

Agent SDK:

• Check email/password
• Token might be expired, call login() again

Server SDK:

• Check API key is correct
• Ensure API key has not been revoked

WebSocket not connecting

• Check network connectivity
• Verify firewall allows WebSocket connections
• Check token is valid (not expired)

Rate limiting (429 error)

• Implement exponential backoff
• Reduce request frequency
• Contact support for rate limit increase

---

Support

• Documentation: https://docs.uchara.com
• GitHub Issues: https://github.com/Uchara-AI/sdk-{platform}/issues
• Email: developers@uchara.com
• Discord: https://discord.gg/uchara

---

Happy coding! 🚀