Basic TypeScript Example

This guide will walk you through setting up a minimal example of an interactive AI avatar using a backend built with TypeScript and Express.

Prerequisites

A TruGen API key (get one here)
A TruGen Agent ID (create and get one here)
Node.js installed on your machine
A modern web browser with microphone access

Project Setup

Install Dependencies

Initialize a new project and install the required runtime and development dependencies:

npm init -y
npm install express dotenv @trugen/js-sdk
npm install -D typescript ts-node @types/express @types/node

Configure TypeScript

Create a tsconfig.json file in the root of your project:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "dist",
    "rootDir": "."
  },
  "include": ["server.ts"],
  "exclude": ["node_modules", "dist"]
}

Set Up Project Structure

Set up the following directory layout:

project/
├── .env
├── server.ts
├── public/
│   └── index.html
├── tsconfig.json
└── package.json

Add Your Credentials

Create a .env file and add your API key and Agent ID:

TRUGEN_API_KEY=your_trugen_api_key
AGENT_ID=your_agent_id

Never expose your API key in the browser. The server reads it from .env and returns only a short-lived session token to the client.

Create the Server

Create server.ts — this fetches the session token on the backend to keep your credentials secure:

import express, { Request, Response } from "express";
import path from "path";
import dotenv from "dotenv";

dotenv.config();

const app = express();

app.use(express.static("public"));

app.get("/token", async (_req: Request, res: Response): Promise<void> => {
  try {
    const response = await fetch("https://api.trugen.ai/v1/auth/conversation", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-Key": process.env.TRUGEN_API_KEY as string,
      },
      body: JSON.stringify({
        agentId: process.env.AGENT_ID,
      }),
    });

    const data = await response.json() as { token: string };

    res.json({ token: data.token });
  } catch (error) {
    console.error(error);
    res.status(500).json({ error: "Failed to create session token" });
  }
});

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

Create the HTML Frontend

Create public/index.html. The frontend runs plain browser JS and imports the SDK from esm.sh directly, so no TypeScript compilation is required for the client side:

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8" />
  <title>TruGen SDK Test (TS)</title>
</head>
<body>

  <h2>TruGen SDK Test (TypeScript Server)</h2>

  <button id="connectBtn">Connect</button>
  <button id="disconnectBtn">Disconnect</button>

  <br /><br />

  <video
    id="avatarVideo"
    autoplay
    playsinline
    style="width:600px;border:1px solid #ccc;"
  ></video>

  <script type="module">
    import { createClient, TruGenEvent } from "https://esm.sh/@trugen/js-sdk";

    let session;

    document.getElementById("connectBtn").addEventListener("click", async () => {
      try {
        const response = await fetch("/token");
        const { token } = await response.json();

        session = await createClient({ token });

        session.on(TruGenEvent.VIDEO_STREAM_STARTED, (track) => {
          track.attach(document.getElementById("avatarVideo"));
        });

        await session.connect();
        console.log("Connected");
      } catch (err) {
        console.error(err);
      }
    });

    document.getElementById("disconnectBtn").addEventListener("click", async () => {
      if (session) {
        await session.disconnect();
        console.log("Disconnected");
      }
    });
  </script>

</body>
</html>

Run the Application

Start the server with ts-node for quick testing without a separate build step:

npx ts-node server.ts

Open http://localhost:3000 in your web browser, allow microphone access, and click Connect.

JavaScript SDK

Python SDK

Prerequisites

Project Setup

​Prerequisites

​Project Setup

Prerequisites

Project Setup