confana-dev

The official Node.js SDK for the Confana AI platform.
Build AI-powered voice agents, transcribe audio, synthesise speech, stream real-time conversations, and trigger phone calls — in minutes.

Installation

npm install confana-dev

Quick Start

import { ConfanaClient } from "confana-dev";

const client = new ConfanaClient({
  api_key:    "YOUR_API_KEY",           // from Dashboard → Settings
  base_url:   "https://api.confana.ai", // your Confana backend (or self-hosted)
  engine_url: "https://engine.confana.ai",
});

Text-to-Speech (TTS)

// Synthesise text → WAV Buffer
const audio = await client.tts.speak("Hello! How can I help you today?");
import fs from "fs/promises";
await fs.writeFile("hello.wav", audio);

// Different language
const audioFr = await client.tts.speak("Bonjour, comment puis-je vous aider?", { language: "fr" });

// Built-in speaker voice
const audioBob = await client.tts.speak("Good morning!", { speaker: "Bob" });

// One-liner to file
await client.tts.speakToFile("Goodbye!", "bye.wav");

// Fine-tune quality
const hq = await client.tts.speak("This sounds amazing!", {
  num_step: 32,       // Diffusion steps 4–50 (higher = better quality)
  temperature: 0.9,   // Expressiveness 0.0–1.5
});

// Zero-shot voice cloning
import fs from "fs/promises";
const refAudio = await fs.readFile("my_voice.wav");
const cloned = await client.tts.speak("Hello in my voice!", {
  voice_clone_audio:    refAudio,
  voice_clone_ref_text: "Hello in my voice!",
});

Real-time TTS streaming (WebSocket)

import Speaker from "speaker";
const spk = new Speaker({ channels: 1, bitDepth: 16, sampleRate: 24000 });

for await (const chunk_b64 of client.tts.stream("Tell me a long story...", { num_step: 32 })) {
  spk.write(Buffer.from(chunk_b64, "base64"));
}
spk.end();

TTS Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | language | string | "en" | BCP-47 language code | | speaker | string\|number | null | Built-in speaker: "Bob", "Tasha", "Kofi", "Adwoa", or index 0–3 | | num_step | number | 32 | Diffusion steps (4–50). Higher = better quality, slower. | | temperature | number | 0.8 | Expressiveness (0.0–1.5). Higher = more varied. | | voice_clone_audio | Buffer | null | Raw audio bytes for voice cloning | | voice_clone_url | string | null | URL of a reference audio file | | voice_clone_ref_text | string | null | Transcript of the reference recording |

Automatic Speech Recognition (ASR)

// Transcribe a file
const text = await client.asr.transcribe("interview.wav");
console.log(text);

// Auto-detect language
const text2 = await client.asr.transcribe("audio.mp3", { language: "auto" });

// Transcribe raw bytes
const bytes = await fs.readFile("speech.wav");
const text3 = await client.asr.transcribeBytes(bytes, { beam_size: 5 });

Real-time microphone streaming

Requires SoX installed on the system.

for await (const utterance of client.asr.streamMicrophone({ language: "en" })) {
  console.log("You said:", utterance);
  if (utterance.toLowerCase().includes("stop")) break;
}

ASR Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | language | string | "auto" | BCP-47 code or "auto" for language detection | | beam_size | number | 5 | Beam search width (1–10). Higher = more accurate, slower. | | temperature | number | 0.0 | Decoding temperature (0.0 = greedy / deterministic) |

LLM Chat

// Single-turn Q&A
const reply = await client.llm.chat("What is a workflow node?");

// Multi-turn conversation (history updated automatically)
const history = [];
await client.llm.chat("Hi! My name is Alice.", { history });
const name = await client.llm.chat("What is my name?", { history });
// → "Your name is Alice."

// Streaming
for await (const token of client.llm.stream("Write a haiku about JavaScript.")) {
  process.stdout.write(token);
}

Agent Sessions

// Load a published agent by ID
const session = await client.agent.session("YOUR_AGENT_ID");

// Text chat
const reply = await session.chat("Book a table for two on Friday.");
console.log(reply);

// Streaming reply
for await (const token of session.stream("What are your hours?")) {
  process.stdout.write(token);
}

// Conversation history
const hist = await session.history();

// Reset memory (keeps session alive)
await session.reset();

// Debug engine state (current graph node, mode, etc.)
console.log(await session.state());

// End and clean up
await session.end();

Voice WebSocket

const ws = session.voice_ws();
await ws.connect();

// Send PCM audio in real time
ws.send_audio(pcmBuffer);        // 16-bit 16 kHz mono PCM
ws.signal_end_of_speech();

// Receive events
for await (const event of ws.events()) {
  if (event.type === "audio_chunk") { /* TTS audio */ }
  if (event.type === "transcript")  { /* STT text  */ }
}

ws.disconnect();

Phone Calls

// Outbound call
const call = await client.phone.call("AGENT_ID", "+12025550178");
console.log("Call SID:", call.call_sid);

// Check status
const status = await client.phone.callStatus(call.call_sid);

// Hang up
await client.phone.hangup(call.call_sid);

// Inbound webhook URL (configure in Twilio console)
const url = client.phone.inboundWebhookUrl("AGENT_ID");

Error Handling

import { ConfanaError, TTSError, ASRError, SessionError } from "confana-dev";

try {
  const audio = await client.tts.speak("Hello!");
} catch (err) {
  if (err instanceof TTSError)     console.error("TTS failed:", err.message);
  if (err instanceof ASRError)     console.error("ASR failed:", err.message);
  if (err instanceof SessionError) console.error("Session error:", err.message);
  else throw err;
}

Supported Languages

| Code | Language | Code | Language | |------|------------|------|------------| | en | English | zh | Chinese | | fr | French | ja | Japanese | | es | Spanish | ko | Korean | | de | German | ar | Arabic | | pt | Portuguese | hi | Hindi | | it | Italian | ru | Russian | | ak | Akan (Twi) | | |

License

MIT © Confana AI