@origonai/web-chat-sdk

A lightweight, UI-agnostic Chat and Voice SDK for integrating Origon/Samespace chat and real-time voice call capabilities into your web applications.

Features

• 🗨️ Real-time Chat — Send and receive messages with streaming support
• 🎙️ Voice Calls — WebRTC-based audio calls with full control
• 🔄 Live Agent Support — Seamless handoff to human agents
• 📜 Chat History — Retrieve and resume previous sessions
• 🎯 Framework Agnostic — Works with React, Vue, Svelte, vanilla JS, or any framework
• 📦 Zero UI Dependencies — Bring your own UI components

Installation

npm install @origonai/web-chat-sdk
# or
yarn add @origonai/web-chat-sdk

Quick Start

Chat Example

import {
  initialize,
  startChat,
  sendMessage,
  disconnect,
  setCallbacks
} from '@origonai/web-chat-sdk'

// 1. Set up callbacks for state updates
setCallbacks({
  onMessageAdd: (message) => {
    console.log('New message:', message)
  },
  onMessageUpdate: (index, updatedMsg) => {
    console.log('Message updated at index:', index, updatedMsg)
  },
  onTyping: (isTyping) => {
    console.log('Live Agent is typing:', isTyping)
  },
  onSessionUpdate: (sessionId) => {
    console.log('Session ID:', sessionId)
  },
  onLiveAgentMode: (isLiveAgent) => {
    console.log('Live agent mode:', isLiveAgent)
  }
})

// 2. Initialize with your endpoint
initialize({
  endpoint: 'https://your-origon-endpoint.com/api/chat'
})

// 3. Start a chat session
const { sessionId, messages, configData } = await startChat()

// 4. Send messages
await sendMessage({ text: 'Hello!' })

// 5. Disconnect when done
disconnect()

Call Example

import {
  initialize,
  startCall,
  disconnectCall,
  toggleMute,
  setCallCallbacks
} from '@origonai/web-chat-sdk'

// 1. Set up call callbacks
setCallCallbacks({
  onCallStatus: (status) => {
    console.log('Call status:', status) // 'connecting' | 'connected' | 'disconnected' | 'error'
  },
  onCallError: (error) => {
    console.error('Call error:', error)
  }
})

// 2. Initialize (same as chat)
initialize({
  endpoint: 'https://your-origon-endpoint.com/api/chat'
})

// 3. Start a voice call
await startCall()

// 4. Toggle mute
const isMuted = toggleMute()

// 5. End the call
disconnectCall()

API Reference

Configuration & Authentication

initialize(credentials)

Initializes the SDK with your credentials.

initialize({
  endpoint: string,     // Required: Your Origon API endpoint
  token?: string,       // Optional: JWT token for authenticated users
  externalId?: string   // Optional: Custom user identifier
})

authenticate(credentials)

Authenticates and retrieves configuration from the server.

const config = await authenticate({
  endpoint: 'https://your-origon-endpoint.com/api/chat'
})

configure(credentials)

Configures the API service with an endpoint (called automatically by authenticate).

configure({ endpoint: 'https://your-endpoint.com/api/chat' })

Chat Functions

setCallbacks(callbacks)

Sets callback functions for chat events.

setCallbacks({
  onMessageAdd: (message: Message) => void,
  onMessageUpdate: (index: number, updatedMsg: Message) => void,
  onTyping: (isTyping: boolean) => void,
  onLiveAgentMode: (isLiveAgent: boolean) => void,
  onSessionUpdate: (sessionId: string) => void
})

startChat(payload?)

Starts a new chat session or resumes an existing one.

const result = await startChat({
  sessionId?: string  // Optional: Resume an existing session
})

// Returns:
// {
//   sessionId: string,
//   messages: Message[],
//   configData: object
// }

sendMessage(message)

Sends a message in the current chat session. Returns a Promise that resolves with the session ID when the bot response is complete.

const sessionId = await sendMessage({
  text: string,   // Required: Message text
  html?: string   // Optional: HTML content
})

disconnect()

Disconnects from the current chat session and cleans up resources.

disconnect()

getHistory()

Retrieves chat history for the current device/user.

const { sessions } = await getHistory()

getMessages(sessionId)

Retrieves messages for a specific session.

const { sessionHistory } = await getMessages('session-id')

Call Functions

setCallCallbacks(callbacks)

Sets callback functions for call events.

setCallCallbacks({
  onCallStatus: (status: string) => void,
  onCallError: (error: string | null) => void
})

startCall(payload?)

Initiates a WebRTC voice call.

await startCall({
  sessionId?: string  // Optional: Associate with existing chat session
})

disconnectCall()

Ends the current voice call and cleans up resources.

disconnectCall()

toggleMute()

Toggles microphone mute state.

const isMuted = toggleMute() // Returns: boolean

getLocalStream()

Returns the local MediaStream for the current call.

const stream = getLocalStream() // Returns: MediaStream | null

getInboundAudioEnergy()

Gets the total audio energy of the inbound audio stream (useful for visualizations).

const energy = await getInboundAudioEnergy() // Returns: number

getOutboundAudioEnergy()

Gets the total audio energy of the outbound audio stream.

const energy = await getOutboundAudioEnergy() // Returns: number

Constants

MESSAGE_ROLES

Enum for message roles in the chat.

import { MESSAGE_ROLES } from '@origonai/web-chat-sdk'

MESSAGE_ROLES.BOT // 'assistant' - AI/bot responses
MESSAGE_ROLES.USER // 'user' - End user messages
MESSAGE_ROLES.AGENT // 'agent' - Human agent messages
MESSAGE_ROLES.SYSTEM // 'system' - System notifications

Types

Message

interface Message {
  id?: string
  text: string
  html?: string
  role: 'assistant' | 'user' | 'agent' | 'system'
  timestamp?: string
  loading?: boolean
  done?: boolean
  errorText?: string
  video?: object // YouTube video data
  channel?: string
}

ChatCallbacks

interface ChatCallbacks {
  onMessageAdd?: (message: Message) => void
  onMessageUpdate?: (index: number, updatedMsg: Message) => void
  onTyping?: (isTyping: boolean) => void
  onLiveAgentMode?: (isLiveAgent: boolean) => void
  onSessionUpdate?: (sessionId: string) => void
}

CallCallbacks

interface CallCallbacks {
  onCallStatus?: (status: 'connecting' | 'connected' | 'disconnected' | 'error') => void
  onCallError?: (error: string | null) => void
}

Advanced Usage

Resuming a Previous Session

// Get session from history
const { sessions } = await getHistory()
const previousSession = sessions[0]

// Resume the session
const { messages } = await startChat({
  sessionId: previousSession.sessionId
})

Authenticated Users

initialize({
  endpoint: 'https://your-endpoint.com/api/chat',
  token: 'your-jwt-token',
  externalId: 'user-123'
})

Combining Chat and Voice

import {
  initialize,
  startChat,
  sendMessage,
  startCall,
  disconnectCall,
  setCallbacks,
  setCallCallbacks
} from '@origonai/web-chat-sdk'

// Set up both chat and call callbacks
setCallbacks({
  onMessageAdd: (message) => addMessageToUI(message),
  onMessageUpdate: (index, updatedMsg) => updateMessageInUI(index, updatedMsg),
  onSessionUpdate: (sessionId) => saveSession(sessionId)
})

setCallCallbacks({
  onCallStatus: (status) => updateCallUI(status)
})

initialize({ endpoint: 'https://your-endpoint.com/api/chat' })

// Start chat
const { sessionId } = await startChat()

// Later, start a voice call in the same session
await startCall({ sessionId })

// Messages and voice share the same session
await sendMessage({ text: 'Can you hear me?' })

Audio Visualization

// Create an audio level meter
async function updateAudioLevel() {
  try {
    const inbound = await getInboundAudioEnergy()
    const outbound = await getOutboundAudioEnergy()

    updateVisualization({ inbound, outbound })
  } catch (e) {
    // Handle no active call
  }
}

setInterval(updateAudioLevel, 100)

Browser Support

• Chrome 80+
• Firefox 78+
• Safari 14+
• Edge 80+

Voice calls require WebRTC support and microphone permissions.

License

MIT © Origon