Skip to main content

​
Introduction

The Alcamine JavaScript SDK provides a type-safe, promise-based interface for connecting your web application to Alcamine voice agents in just a few lines of code. All networking and media handling is taken care of behind the scenes so you can focus on building great experiences.

​
When should I use it?

  1. Spin up a new realtime voice session with an Alcamine agent.
  2. Resume an existing conversation.
  3. Interact with the underlying room object (subscribe to tracks, mute/unmute, etc.).
  4. Capture analytics events inside your product.
If you only need to call the REST API (for example from your backend) take a look at our HTTP reference.

​
Installation

# Using npm
npm install alcamine

# Using yarn
yarn add alcamine

​
Quick start

import { alcamine } from 'alcamine';

// 1. Initialize the library once, as early as possible
alcamine.init('pk_live_1234567', {
  debug: import.meta.env.DEV, // optional
  baseUrl: 'https://api.alcamine.com', // optional
});

// 2. Create a new session with one of your agents
const { session } = await alcamine.connect({
  agentId: 'agt_8w9d2kfe',
});

// 3. Get access to the underlying room instance
const room = alcamine.getRoom(session.id);
room.on('participantJoined', (p) => console.log('👋', p.identity));

// 4. End the call when you're done
await alcamine.disconnect(session.id);
…and that’s it! Your browser’s microphone is automatically enabled and audio is sent to the agent as soon as the room connects.

​
API reference

​
alcamine.init(publicKey: string, config?: AlcamineConfig)

Initializes the SDK. Must be called before any other method. Calling init() more than once is a no-op and will log a warning in development.
ParameterTypeDescription
publicKeystringThe public key found in the Alcamine dashboard.
config.baseUrlstring(optional) Override the base URL if you are self-hosting or using a preview environment.
config.debugboolean(optional) When true the SDK prints verbose logs and sets window.DEBUG = true.

​
alcamine.connect(options): Promise<{ session: Session }>

Starts or resumes a voice session.
PropertyTypeRequiredDescription
agentIdstring✓ (unless sessionId supplied)The ID of the agent to talk to.
sessionIdstringResume an existing session instead of creating a new one.
previewTokenstringAllows connecting to unpublished agents.
agentVersionIdstringSpecific version to preview (requires previewToken).
When resolved you receive session – an object containing id, timestamps and other metadata. A room is created in the background and microphone input is buffered until the connection is fully established.

​
alcamine.disconnect(sessionId?: string): Promise<void>

Gracefully ends the audio call and marks the session as completed in Alcamine.
  • If sessionId is provided, only that room is disconnected.
  • If omitted, all active rooms are disconnected – handy for global clean-up, for example in a window.beforeunload handler.

​
alcamine.getRoom(sessionId: string): Room | undefined

Returns the underlying room instance so you can:
  • Listen to room-level events (participantJoined, trackSubscribed, …).
  • Toggle microphone or speaker state.
  • Access statistics such as RTT and packet loss.
const room = alcamine.getRoom(session.id);
room.localParticipant.setMicrophoneEnabled(false);

​
alcamine.captureEvent(name: string, properties: Record<string, any>): Promise<void>

Optional helper that sends a custom analytics event to Alcamine. Events show up in your analytics dashboard in real-time and can be used to build funnels or triggers. 
await alcamine.captureEvent('Purchased', {
  plan: 'pro',
  amount: 1999,
});

​
Type definitions

The SDK ships with full TypeScript typings. Key interfaces: 
type Session = {
  id: string;
  agentId: string;
  startedAt: string;
  completedAt?: string;
  // ...additional fields
};

interface AlcamineConfig {
  baseUrl?: string;
  debug?: boolean;
}
Hover over methods in your editor to see the complete types.

​
Error handling

All methods throw standard JavaScript errors for fatal conditions, so wrap async calls in try/catch or use .catch() to handle them gracefully. 
try {
  const { session } = await alcamine.connect({ agentId: 'agt_...' });
} catch (err) {
  console.error('Unable to connect to agent', err);
}

​
Troubleshooting

  • You have already initialized Alcamine! – init() was called more than once. This is safe to ignore, but you probably want to remove the duplicate call.
  • Room not found – you called getRoom() with a wrong or expired sessionId.
  • Continuous reconnections – check that your firewall allows WebRTC traffic.

​
Next steps

  • Read the HTTP API reference for low-level control.
  • Explore our React hooks package for rapid UI integration.
  • Join the community on Discord to share what you build and get help!
Happy coding! 👋