Chat SDK
Build custom chat interfaces with intelligent agent handoff, live status awareness, and offline handling.
Introduction
The Ryoku Chat SDK lets you create fully custom chat experiences while handling the complexity of agent availability, real-time handoffs, and offline message capture.
Agent Status
Know if agents are online before offering live chat.
Live Handoff
Real-time transfer to human agents.
Offline Capture
Email leads when no agents are available.
Installation
Import the SDK from your Ryoku instance.
import { RyokuChat } from "@/lib/sdk/public";Quick Start
Choose how you want to integrate - use our widget, embed our chat, or build fully custom.
Option 1: Embed Widget
Add this script to your website:
<script
src="https://your-domain.com/widget.js"
data-slug="your-business"
data-position="bottom-right"
data-theme="dark"
data-color="#6366f1"
></script>Option 2: Embed Chat Page
Use an iframe to embed the chat interface:
<iframe
src="https://your-domain.com/chat/your-business?embed=1"
style="width: 400px; height: 600px; border: none;"
></iframe>Option 3: Custom UI (SDK)
const ryoku = new RyokuChat({
baseUrl: "https://your-ryoku-instance.com",
pusherKey: "your-pusher-key",
pusherCluster: "us2"
});
// Send a message
const session = ryoku.getSession("your-business");
await ryoku.chat({
slug: "your-business",
messages: [{ role: "user", content: "Hello!" }],
onMessage: (delta) => updateUI(delta),
onFinish: (full) => saveResponse(full)
});Agent Status
Check if live agents are available before showing the "Chat with agent" option.
const status = await ryoku.checkAgentStatus("your-business");
if (status.online) {
// Show "Chat with agent" button
console.log(`${status.onlineCount} agents available`);
} else {
// Show offline contact form
}
// List all agents
status.agents.forEach(agent => {
console.log(`${agent.name}: ${agent.status}`);
});Recommended Flow
Check agent status on page load, then show live chat or offline form accordingly.
Streaming Chat
The chat() method sends messages and streams responses token-by-token.
await ryoku.chat({
slug: "your-business",
messages: [
{ role: "user", content: "I need help with my order" }
],
onMessage: (delta) => {
// Called for each token
appendToResponse(delta);
},
onError: (err) => {
showError(err.message);
},
onFinish: (fullResponse) => {
// Called when complete
saveToHistory(fullResponse);
}
});| Param | Type | Description |
|---|---|---|
| slug | string | Your business slug |
| messages | Message[] | Conversation history |
| onMessage | function | Token callback |
Human Escalation
Request a live agent to take over the conversation.
await ryoku.escalate({
slug: "your-business",
conversationId: session.id,
reason: "Customer requested human agent",
email: "customer@example.com",
phone: "+1234567890" // optional
});Offline Queries
Capture lead information when no agents are online.
await ryoku.sendOfflineQuery({
slug: "your-business",
name: "John Doe",
email: "john@example.com",
query: "Do you offer enterprise pricing?"
});Session Management
Get Session
const session = ryoku.getSession("slug");
console.log(session.id);Reset Session
ryoku.resetSession("slug");Real-time Events
Subscribe to live agent handoffs and status changes.
// Listen for agent taking over
const unsub = ryoku.subscribe(session.id, "bot-handoff", (data) => {
showToast("Agent joined!");
setLiveChatMode(true);
});
// Listen for agent coming online
const unsubStatus = ryoku.subscribeToAgentStatus(businessId, (data) => {
if (data.online) enableLiveChat();
});
// Cleanup
ryoku.destroy();TypeScript Types
interface Message {
role: "user" | "assistant" | "system" | "tool";
content: string;
}
interface AgentStatus {
online: boolean;
onlineCount: number;
agents: {
id: string;
name: string;
avatar: string | null;
status: "online" | "away" | "offline";
}[];
}API Endpoints
If not using the SDK, you can call these endpoints directly:
| Endpoint | Method | Description |
|---|---|---|
| /api/chat/[slug] | POST | Send chat message |
| /api/agent/status | GET | Check agent availability |
| /api/chat/escalate | POST | Request agent handoff |
| /api/chat/offline-query | POST | Submit offline message |
Build your own UI
Use the SDK to create fully custom chat experiences.