The Anam API provides a simple interface for implementing digital AI personas within your web applications. This guide will walk you through the process of setting up a minimal example of an interactive AI persona. By the end, you’ll have a working persona that can have real-time conversations in your web application.

​
Prerequisites

  • Node.js (version 16 or higher) and npm installed on your system
  • Basic knowledge of JavaScript
  • An Anam API key (get one here)
  • A microphone and speakers for voice interaction

​
Project Setup

This quickstart creates a minimal web application with three main files organized in a simple project structure:

my-anam-app/
├── server.js          # Express server for secure API key handling
├── package.json       # Node.js dependencies
├── public/            # Static files served to the browser
│   ├── index.html     # Main HTML page with video element
│   └── script.js      # Client-side JavaScript for persona control
└── .env               # Environment variables (optional)
1

Create project directory

mkdir my-anam-app
cd my-anam-app
2

Initialize Node.js project

npm init -y

This creates a package.json file for managing dependencies.

3

Create public directory

mkdir public

The public folder will contain your HTML and JavaScript files that are served to the browser.

4

Install dependencies

npm install express dotenv

We’re installing Express for the server and dotenv for environment variable management. The Anam SDK will be loaded directly from a CDN in the browser.

5

Create environment file

Create a .env file in your project root to store your API key securely:

.env
ANAM_API_KEY=your-api-key-here

Replace your-api-key-here with your actual Anam API key. Never commit this file to version control.

​
Step 1: Set up your server

For this example, we’ll create a basic Express server to handle session token generation. In a real application, you should integrate this functionality into your existing backend service.

server.js (Node.js example)
require('dotenv').config();
const express = require('express');
const app = express();

app.use(express.json());
app.use(express.static('public'));

app.post('/api/session-token', async (req, res) => {
  try {
    const response = await fetch("https://api.anam.ai/v1/auth/session-token", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${process.env.ANAM_API_KEY}`,
      },
      body: JSON.stringify({
        personaConfig: {
          name: "Cara",
          avatarId: "30fa96d0-26c4-4e55-94a0-517025942e18",
          voiceId: "6bfbe25a-979d-40f3-a92b-5394170af54b",
          brainType: "ANAM_GPT_4O_MINI_V1",
          systemPrompt: "You are Cara, a helpful customer service representative. Be friendly and concise in your responses.",
        },
      }),
    });
    
    const data = await response.json();
    res.json({ sessionToken: data.sessionToken });
  } catch (error) {
    res.status(500).json({ error: 'Failed to create session' });
  }
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

The server endpoint exchanges your API key and persona configuration for a temporary session token that the client can safely use. This token has limited scope and expires, providing an additional security layer.

​
Step 2: Set up your HTML

Create a simple HTML page with a video element for the persona and controls to start/stop the chat:

index.html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My First Anam Persona</title>
</head>
<body>
    <div style="text-align: center; padding: 20px;">
        <h1>Chat with Cara</h1>
        <video id="persona-video" autoplay playsinline style="max-width: 100%; border-radius: 8px;"></video>
        <div style="margin-top: 20px;">
            <button id="start-button">Start Chat</button>
            <button id="stop-button" disabled>Stop Chat</button>
        </div>
    </div>
    <script type="module" src="script.js"></script>
</body>
</html>

​
Step 3: Initialize the Anam client

Create the client-side JavaScript to control your persona connection:

script.js
import { createClient } from "https://esm.sh/@anam-ai/js-sdk@latest";

let anamClient = null;

// Get DOM elements
const startButton = document.getElementById("start-button");
const stopButton = document.getElementById("stop-button");
const videoElement = document.getElementById("persona-video");

async function startChat() {
  try {
    startButton.disabled = true;

    // Get session token from your server
    const response = await fetch("/api/session-token", {
      method: "POST",
    });
    const { sessionToken } = await response.json();

    // Create the Anam client
    anamClient = createClient(sessionToken);

    // Start streaming to the video element
    await anamClient.streamToVideoElement("persona-video");

    // Update button states
    startButton.disabled = true;
    stopButton.disabled = false;

    console.log("Chat started successfully!");
  } catch (error) {
    console.error("Failed to start chat:", error);
    startButton.disabled = false;
  }
}

function stopChat() {
  if (anamClient) {
    // Disconnect the client
    anamClient.stopStreaming();
    anamClient = null;

    // Clear video element
    videoElement.srcObject = null;

    // Update button states
    startButton.disabled = false;
    stopButton.disabled = true;

    console.log("Chat stopped.");
  }
}

// Add event listeners
startButton.addEventListener("click", startChat);
stopButton.addEventListener("click", stopChat);

​
Step 4: Run your application

  1. Start your server:
node server.js

  1. Open http://localhost:3000 in your browser

  2. Click “Start Chat” to begin your conversation with Cara!

You should see Cara appear in the video element and be ready to chat through voice interaction.

​
What’s happening?

  1. Server-Side Security: Your server safely exchanges your API key for a session token, keeping credentials secure
  2. Client Connection: The SDK creates a WebRTC connection for real-time video streaming when you start the chat
  3. Voice Interaction: Cara listens for your voice input and responds with synchronized audio and video
  4. Connection Control: Start and stop buttons give you full control over when the persona is active

​
Next Steps

Core Concepts

Learn how personas, tokens, and streaming work

Customize Your Persona

Change appearance, voice, and behavior

Handle Events

React to conversation events and user interactions

Production Setup

Deploy your persona securely at scale

​
Common Issues

Persona not appearing?

  • Check that your API key is set correctly
  • Ensure the video element has autoplay and playsinline attributes
  • Check browser console for errors

No audio?

  • Make sure your browser allows autoplay with sound
  • Check that the user has interacted with the page first (clicking “Start Chat” counts)

Connection issues?

  • Verify your server can reach api.anam.ai
  • Check network connectivity and firewall settings