@hubui/client

Official JavaScript/TypeScript SDK for HubUI — Connect your applications to AI voice and text agents.

SDK Version: 0.1.0

Get Started Free · Documentation · Discord

Why HubUI Client?

If you already have a web app — React, Next.js, Vue, plain HTML — HubUI Client lets you drop in a real-time voice or text AI agent with a few lines of code. No WebRTC plumbing. No socket management. No audio handling.

Your users get a real-time conversation with an AI agent — voice with sub-500ms latency, or streaming text chat — and you get a clean event-driven API. Connect, listen for events, done.

The Client SDK handles the browser side. HubUI handles everything else — speech-to-text, LLM inference, text-to-speech, and phone numbers.

Building a custom reasoning backend? Use the HubUI Brain SDK (Python) to plug in your own LLM, LangChain, or LangGraph pipeline.

Installation

From npm (recommended)

npm install @hubui/client

From GitHub repository

npm install github:HubUI-AI/hubui-client

If your environment requires explicit Git URLs:

npm install git+https://github.com/HubUI-AI/hubui-client.git

Before You Start

• Free HubUI account (sign up in seconds)
• Agent created in the HubUI Dashboard
• API key (pk_live_...) from Dashboard > Settings > API Keys
• agentId from the Agents page

Quick Start

Voice Mode

import { HubUI } from '@hubui/client';

// Connect to your agent in voice mode
const session = await HubUI.connect({
  agentId: 'your-agent-id',      // From HubUI Dashboard
  apiKey: 'pk_live_xxxxx',        // From HubUI Dashboard > Settings > API Keys
  mode: 'voice',
  userName: 'John Doe',           // Optional: End user's name
});

// Listen for transcripts
session.on('transcript', (text, speaker, isFinal) => {
  console.log(`${speaker}: ${text}`);
});

// Handle connection state
session.on('connectionStateChanged', (state) => {
  console.log('Connection:', state);
});

// Mute/unmute controls
session.mute();
session.unmute();

// Disconnect when done
await session.disconnect();

Text Mode

import { HubUI } from '@hubui/client';

// Connect to your agent in text mode
const session = await HubUI.connect({
  agentId: 'your-agent-id',
  apiKey: 'pk_live_xxxxx',
  mode: 'text',
  userName: 'John Doe',
});

// Listen for agent responses
session.on('message', (text) => {
  console.log('Agent:', text);
});

// Send messages
await session.send('Hello! How can you help me?');

// Disconnect when done
await session.disconnect();

API Reference

HubUI.connect(config)

Connects to a HubUI agent and returns a session.

Parameters:

| Property | Type | Required | Description | |----------|------|----------|-------------| | agentId | string | Yes | Your agent ID from the dashboard | | apiKey | string | Yes* | Your API key (pk_live_...) | | token | string | No | Pre-fetched realtime token (advanced usage) | | serverUrl | string | No | Realtime server URL (required when token is provided) | | mode | 'voice' \| 'text' | Yes | Connection mode | | userName | string | No | End user's display name | | userEmail | string | No | End user's email | | audioInput | string | No | Audio input device ID | | audioOutput | string | No | Audio output device ID | | apiBaseUrl | string | No | Custom HubUI API base URL | | debug | boolean | No | Enable SDK debug logging (default: false) |

Returns: Promise<HubUISession>

* apiKey is required unless you provide token + serverUrl.

HubUI.getAudioDevices()

Lists available audio input and output devices.

const { inputs, outputs } = await HubUI.getAudioDevices();

console.log('Microphones:', inputs);
console.log('Speakers:', outputs);

HubUISession

Properties

| Property | Type | Description | |----------|------|-------------| | state | HubUIConnectionState | Current connection state | | mode | 'voice' \| 'text' | Current mode | | transcript | HubUITranscriptEntry[] | Full conversation transcript |

Methods

| Method | Description | |--------|-------------| | on(event, callback) | Subscribe to events | | off(event, callback) | Unsubscribe from events | | mute() | Mute microphone (voice mode) | | unmute() | Unmute microphone (voice mode) | | isMuted() | Check if muted | | enableAudio() | Enable audio (required on mobile) | | send(message) | Send text message | | setAudioInput(deviceId) | Change microphone | | setAudioOutput(deviceId) | Change speaker | | disconnect() | End the session |

Events

| Event | Callback | Description | |-------|----------|-------------| | connected | () => void | Connected to agent | | disconnected | () => void | Disconnected from agent | | error | (error: HubUIError) => void | Error occurred | | transcript | (text, speaker, isFinal) => void | Voice transcript received | | message | (text) => void | Text message received | | connectionStateChanged | (state) => void | State changed | | audioPlaybackBlocked | () => void | Audio blocked (call enableAudio()) |

Mobile Browser Support

Mobile browsers require a user gesture to play audio. Handle this with:

session.on('audioPlaybackBlocked', () => {
  // Show UI prompting user to tap
  showButton('Tap to enable audio', async () => {
    await session.enableAudio();
  });
});

Error Handling

import { HubUI, HubUIError, ErrorCodes } from '@hubui/client';

try {
  const session = await HubUI.connect(config);
} catch (error) {
  if (error instanceof HubUIError) {
    switch (error.code) {
      case ErrorCodes.INVALID_API_KEY:
        console.error('Invalid API key');
        break;
      case ErrorCodes.INVALID_AGENT_ID:
        console.error('Agent not found');
        break;
      default:
        console.error('Error:', error.message);
    }
  }
}

TypeScript Support

Full TypeScript support with exported types:

import type {
  HubUIConfig,
  HubUIConnectionState,
  HubUITranscriptEntry,
  AudioDevice,
} from '@hubui/client';

Browser Support

• Chrome 70+
• Firefox 65+
• Safari 14+
• Edge 79+

Support

• Read the docs — full platform documentation
• Join the Discord — get help, share what you're building
• Email: [email protected]
• Dashboard: https://app.hubui.ai

License

This software is licensed under the Apache License 2.0.