SDK - Alcamine API

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?

Spin up a new realtime voice session with an Alcamine agent.
Resume an existing conversation.
Interact with the underlying room object (subscribe to tracks, mute/unmute, etc.).
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.

Parameter	Type	Description
`publicKey`	string	The public key found in the Alcamine dashboard.
`config.baseUrl`	string	(optional) Override the base URL if you are self-hosting or using a preview environment.
`config.debug`	boolean	(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.

Property	Type	Required	Description
`agentId`	string	✓ (unless `sessionId` supplied)	The ID of the agent to talk to.
`sessionId`	string		Resume an existing session instead of creating a new one.
`previewToken`	string		Allows connecting to unpublished agents.
`agentVersionId`	string		Specific 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! 👋

​Introduction

​When should I use it?

​Installation

​Quick start

​API reference

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

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

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

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

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

​Type definitions

​Error handling

​Troubleshooting

​Next steps