Basic Usage

Install, setup, and deploy the Anam AI JavaScript SDK

Installation

Install the SDK in your project using npm:

npm install @anam-ai/js-sdk

Browser Requirements

The Anam SDK uses WebRTC for real-time video and audio streaming. Ensure your target browsers support:

• WebRTC (Chrome 56+, Firefox 44+, Safari 11+, Edge 79+)
• MediaDevices API for microphone access

HTML Setup

This example requires a video element to display the persona:

<video id="video-element-id" autoplay playsinline></video>

autoplay starts the stream when the page loads. playsinline prevents fullscreen mode on mobile devices.

Basic Usage

To keep your API key secure, exchange it for a short-lived session token on your server before initializing the client. See Usage in Production for detailed session token information.

Initialize the Client

Use createClient with your session token:

import { createClient, AnamEvent } from "@anam-ai/js-sdk";

const anamClient = createClient(sessionToken);

Start Streaming

Stream the persona to your video element:

try {
  await anamClient.streamToVideoElement("video-element-id");
} catch (error) {
  console.error("Failed to start stream:", error);
}

Listen for Events

Handle connection lifecycle events:

import { AnamEvent, ConnectionClosedCode } from "@anam-ai/js-sdk";

anamClient.addListener(AnamEvent.CONNECTION_ESTABLISHED, () => {
  console.log("Connected to persona");
});

anamClient.addListener(AnamEvent.CONNECTION_CLOSED, (code: ConnectionClosedCode) => {
  console.log("Connection closed:", code);
});

Stopping a Stream

To stop an active session and release resources:

await anamClient.stopStreaming();

Client Options

The createClient function accepts an optional second parameter for configuration:

import { createClient } from "@anam-ai/js-sdk";

const anamClient = createClient(sessionToken, {
  disableInputAudio: false,      // Set true to disable microphone
  audioDeviceId: "device-id",    // Specify audio input device
  voiceDetection: {
    endOfSpeechSensitivity: 0.5, // 0-1, higher = more sensitive
  },
  iceServers: [],                // Custom ICE/TURN servers for WebRTC
  rtcConfiguration: {            // Full RTCConfiguration passthrough (advanced)
    iceTransportPolicy: "relay", // Force TURN-relay-only on UDP-blocked networks
  },
  metrics: {
    disableClientMetrics: false, // Disable telemetry for air-gapped environments
  },
});

Forcing TURN relay — rtcConfiguration is passed directly to the browser’s RTCPeerConnection, so you can set any native WebRTC option. The most common is iceTransportPolicy: "relay", which routes all media through Anam’s TURN servers on networks that block direct or UDP connectivity. See Network Configuration.

ICE-server precedence (highest to lowest): the top-level iceServers option, then rtcConfiguration.iceServers, then Anam’s server-provided defaults. The resolved iceServers always takes the iceServers field, so combining both options is safe.

Troubleshooting

Issue	Solution
Video not appearing	Verify the video element ID matches and has autoplay playsinline attributes
No microphone access	Ensure HTTPS (required for getUserMedia) and user has granted permission
Connection fails	Check browser console for errors; verify session token is valid and not expired

Next Steps

Talk Commands

Control persona output using talk commands

Audio Control

Control audio input and streaming behavior

User Messages

Send messages programmatically on behalf of the user

Events

Handle connection and conversation events