Whissle AI Node.js SDK

Node.js TypeScript SDK for Whissle Gateway -- ASR, TTS, Voice Calling, and Agent services.

Updating README.

Installation

npm install whissle-ai-sdk

Configuration

Create a config.yaml in your project root:

gateway:
  baseUrl: "http://localhost:9000"
  token: "wh_YOUR_TOKEN"

asr:
  baseUrl: "http://localhost:8001"

tts:
  baseUrl: "http://localhost:8003"

agent:
  baseUrl: "http://localhost:8765"

defaults:
  language: "auto"
  model: "default"
  diarize: false
  punctuation: true
  itn: true
  tts_voice: "af_heart"

Or pass configuration directly:

import { WhissleClient } from 'whissle-ai-sdk';

const client = new WhissleClient({
  gatewayUrl: 'http://localhost:9000',
  token: 'wh_YOUR_TOKEN',
});

Quick Start

ASR -- Batch Transcription

import { readFileSync } from 'fs';
import { WhissleClient } from 'whissle-ai-sdk';

const client = new WhissleClient();

const result = await client.asr.transcribe({
  file: readFileSync('call.mp3'),
  filename: 'call.mp3',
  diarize: true,
  num_speakers: 2,
  word_timestamps: true,
  summarize: 'sales_coaching',
});

console.log(result.transcript);
console.log(result.segments);
console.log(result.analysis);

ASR -- WebSocket Streaming

import { readFileSync } from 'fs';
import { WhissleClient } from 'whissle-ai-sdk';

const client = new WhissleClient();
const stream = client.createASRStream();

stream.on('open', () => {
  stream.configure({ language: 'en', interim_results: true });

  const audio = readFileSync('audio.wav');
  const chunkSize = 3200; // 100ms at 16kHz s16le
  let offset = 0;

  const interval = setInterval(() => {
    if (offset >= audio.length) {
      clearInterval(interval);
      stream.end();
      return;
    }
    stream.sendAudio(audio.subarray(offset, offset + chunkSize));
    offset += chunkSize;
  }, 50);
});

stream.on('transcript', (data) => {
  if (!data.is_final) {
    console.log('interim:', data.text);
  }
});

stream.on('final', (data) => {
  console.log('final:', data.text);
  console.log('metadata:', data.metadata);
});

stream.on('end', () => {
  console.log('stream ended');
  stream.close();
});

stream.on('error', (err) => {
  console.error('stream error:', err);
});

stream.connect();

TTS -- Text-to-Speech

import { writeFileSync } from 'fs';
import { WhissleClient } from 'whissle-ai-sdk';

const client = new WhissleClient();

const audio = await client.tts.synthesize('Hello from Whissle Gateway.', {
  voice: 'af_heart',
  speed: 1.0,
});

writeFileSync('output.raw', audio);

Or use the streaming API:

const stream = client.tts.createStream();
await stream.connect();

const chunks: Buffer[] = [];

stream.on('audio', (chunk) => {
  chunks.push(chunk);
});

stream.on('done', () => {
  const audio = Buffer.concat(chunks);
  writeFileSync('output.raw', audio);
  stream.close();
});

stream.configure({ voice: 'af_heart' });
stream.speak({ text: 'Hello from Whissle Gateway.' });

List Available Voices

const voices = await client.tts.getVoices();
console.log(voices.voices);

Agent -- Single-Turn Processing

const result = await client.agent.process({
  transcript: 'What meetings do I have today?',
  user_id: 'user-1',
  language: 'en',
});

console.log(result.processed_text);

Agent -- Multi-Turn Chat (Streaming)

const stream = client.agent.chatStream({
  messages: [
    { role: 'user', content: 'Summarize the key takeaways.' },
  ],
  user_id: 'user-1',
});

for await (const chunk of stream) {
  if (chunk.type === 'text_chunk') {
    process.stdout.write(chunk.content ?? '');
  }
}

Token Management (Admin)

Admin token is required for these operations.

// Create a token for a user
const tokenResponse = await client.auth.createToken({
  user_id: 'my-app',
  label: 'My Application',
});
console.log(tokenResponse.token);

// List all tokens
const tokens = await client.auth.listTokens();

// Revoke a token
await client.auth.revokeToken(tokenId);

// Get usage for a user
const usage = await client.auth.getUsage('user-1', 7);

// Get aggregated usage summary
const summary = await client.auth.getUsageSummary();

User Authentication

// Sign up
await client.userAuth.signup({
  email: 'user@example.com',
  password: 'securepass123',
});

// Login (cookies are stored automatically)
await client.userAuth.login({
  email: 'user@example.com',
  password: 'securepass123',
});

// Get current user
const me = await client.userAuth.getMe();

// Guest access (no credentials needed)
await client.userAuth.guest();

// Forgot password
await client.userAuth.forgotPassword('user@example.com');

// Reset password
await client.userAuth.resetPassword({
  token: 'token-from-email',
  password: 'newpassword123',
});

// Verify email
await client.userAuth.verifyEmail({ token: 'token-from-email' });

// Get auth configuration
const config = await client.userAuth.getConfig();

// Google OAuth
const googleUrl = client.userAuth.getGoogleOAuthUrl();

Voice Calling

Voice Agents

// Create a voice agent
const agent = await client.voiceCalling.createAgent({
  name: 'Sales Rep',
  system_prompt: 'You are a helpful sales assistant for Acme Corp.',
  greeting: 'Hi there! How can I help you today?',
  voice: 'tara',
  voice_gender: 'female',
  llm_model: 'gemini-2.5-flash',
});

// List agents
const agents = await client.voiceCalling.listAgents();

// Get agent by ID
const agentDetails = await client.voiceCalling.getAgent(agent.id);

// Update agent
await client.voiceCalling.updateAgent(agent.id, {
  name: 'Senior Sales Rep',
});

// Delete agent
await client.voiceCalling.deleteAgent(agent.id);

WebRTC Signaling

// Start a voice session
const answer = await client.voiceCalling.sendOffer({
  sdp: browserSDP,
  type: 'offer',
  agent_id: agent.id,
});

// Send ICE candidates
await client.voiceCalling.sendICETrickle({
  pc_id: answer.pc_id,
  candidates: [{ candidate: '...' }],
});

Customers

// Create a customer
const customer = await client.voiceCalling.createCustomer({
  name: 'Jane Smith',
  phone_number: '+14155551234',
  email: 'jane@example.com',
});

// List customers
const customers = await client.voiceCalling.listCustomers();

// Get customer by ID
const customerDetails = await client.voiceCalling.getCustomer(customer.id);

// Update customer
await client.voiceCalling.updateCustomer(customer.id, {
  name: 'Jane Doe',
});

// Delete customer
await client.voiceCalling.deleteCustomer(customer.id);

Calls

// List calls
const calls = await client.voiceCalling.listCalls({
  agent_id: agent.id,
  limit: 10,
});

// Start an outbound call
const call = await client.voiceCalling.startCall({
  agent_id: agent.id,
  customer_id: customer.id,
  phone_number: '+14155551234',
});

Organizations

// Create an organization
const org = await client.organizations.create({
  name: 'Acme Corp',
  slug: 'acme',
});

// List organizations
const orgs = await client.organizations.list();

// Get active organization
const active = await client.organizations.getActive();

// Switch active organization
await client.organizations.switchOrg({ organization_id: org.id });

// Get organization details
const orgDetails = await client.organizations.get(org.id);

// Update organization
await client.organizations.update(org.id, { name: 'Acme Corporation' });

// Delete organization (owner only)
await client.organizations.delete(org.id);

// List members
const members = await client.organizations.listMembers(org.id);

// Change member role
await client.organizations.updateMemberRole(org.id, userId, { role: 'admin' });

Invitations

// Invite a user
const invitation = await client.organizations.createInvitation(org.id, {
  email: 'colleague@example.com',
  role: 'member',
});

// List pending invitations
const invitations = await client.organizations.listInvitations(org.id);

// Revoke an invitation
await client.organizations.revokeInvitation(org.id, invitation.id);

// Preview an invitation (public)
const preview = await client.organizations.previewInvitation('invitation-token');

// Accept an invitation
await client.organizations.acceptInvitation({
  token: 'invitation-token-from-email',
});

ASR Info Endpoints

// List loaded ASR models
const models = await client.asr.getModels();

// List available intent labels
const intents = await client.asr.getIntents();

// List supported languages
const languages = await client.asr.getLanguages();

// Server status
const status = await client.asr.getStatus();

Additional ASR Endpoints

import { readFileSync } from 'fs';

// Clean transcript (text only, fastest)
const text = await client.asr.transcribeClean({
  file: readFileSync('audio.mp3'),
  filename: 'audio.mp3',
});

// Raw model output
const raw = await client.asr.transcribeRaw({
  file: readFileSync('audio.mp3'),
  filename: 'audio.mp3',
});

// Transcribe raw PCM audio
const pcmResult = await client.asr.transcribePCM({
  audio: readFileSync('audio.pcm'),
  sample_rate: 16000,
});

// Long audio with VAD segmentation
const longResult = await client.asr.transcribeLong({
  file: readFileSync('long-audio.mp3'),
  filename: 'long-audio.mp3',
  diarize: true,
});

// Batch transcription
const batchResults = await client.asr.transcribeBatch({
  files: [
    { file: readFileSync('call1.mp3'), filename: 'call1.mp3' },
    { file: readFileSync('call2.mp3'), filename: 'call2.mp3' },
  ],
  diarize: true,
});

Error Handling

import { WhissleAPIError, WhissleWebSocketError } from 'whissle-ai-sdk';

try {
  await client.asr.transcribe({ file: readFileSync('audio.mp3') });
} catch (err) {
  if (err instanceof WhissleAPIError) {
    console.error(`API error ${err.statusCode}: ${err.body}`);
  } else if (err instanceof WhissleWebSocketError) {
    console.error(`WebSocket error: ${err.message}`);
  }
}

API Reference

WhissleClient

Property	Type	Description
asr	ASRClient	Batch transcription endpoints
tts	TTSClient	Text-to-speech endpoints
agent	AgentClient	Agent process and chat endpoints
auth	AuthClient	Admin token management
userAuth	UserAuthClient	User authentication (signup, login, etc.)
voiceCalling	VoiceCallingClient	Voice agents, customers, calls, WebRTC
organizations	OrganizationsClient	Organizations and invitations

ASRClient

Method	Description
transcribe(params)	Full transcription with all options
transcribeClean(params)	Clean transcript text only
transcribeRaw(params)	Raw model output
transcribePCM(params)	Transcribe raw PCM audio
transcribeLong(params)	Long audio with VAD segmentation
transcribeBatch(params)	Batch multiple files
getModels()	List loaded ASR models
getIntents()	List available intent labels
getLanguages()	List supported languages
getStatus()	Server status

TTSClient

Method	Description
createStream()	Create a TTS WebSocket stream
getVoices()	List available voices
synthesize(text, options?)	Synthesize text to audio buffer

AgentClient

Method	Description
process(params)	Single-turn agent processing
chatStream(params)	Multi-turn chat with SSE streaming

AuthClient

Method	Description
createToken(params)	Create a new API token
listTokens(userId?)	List active tokens
revokeToken(tokenId)	Revoke a token
getUsage(userId, days?)	Usage logs for a user
getUsageSummary()	Aggregated usage stats

UserAuthClient

Method	Description
signup(params)	Register with email + password
login(params)	Login (stores cookies)
logout()	Clear session
refresh()	Rotate tokens
getMe()	Get current user profile
guest()	Create guest session
forgotPassword(email)	Send password reset email
resetPassword(params)	Reset password with token
verifyEmail(params)	Verify email with token
resendVerification()	Resend email verification
getConfig()	Auth configuration
getGoogleOAuthUrl()	Google OAuth URL

VoiceCallingClient

Method	Description
listAgents()	List voice agents
createAgent(params)	Create a voice agent
getAgent(id)	Get agent by ID
updateAgent(id, params)	Update agent settings
deleteAgent(id)	Delete an agent
sendOffer(params)	Send WebRTC SDP offer
sendICETrickle(params)	Send ICE candidates
listCustomers()	List customers
createCustomer(params)	Create a customer
getCustomer(id)	Get customer by ID
updateCustomer(id, params)	Update customer
deleteCustomer(id)	Delete customer
listCalls(params?)	List calls
startCall(params)	Start an outbound call

OrganizationsClient

Method	Description
list()	List user's organizations
create(params)	Create an organization
getActive()	Get active organization
switchOrg(params)	Switch active organization
get(id)	Get organization details
update(id, params)	Update organization
delete(id)	Delete organization (owner only)
listMembers(orgId)	List organization members
updateMemberRole(orgId, userId, params)	Change member role
listInvitations(orgId)	List pending invitations
createInvitation(orgId, params)	Create an invitation
revokeInvitation(orgId, invitationId)	Revoke an invitation
previewInvitation(token)	Preview invitation details
acceptInvitation(params)	Accept an invitation

License

MIT