@superuai/superu-webcall

A framework-agnostic package to seamlessly integrate SuperU Voice AI Agents into your web applications using LiveKit.

Installation

Install the package via npm:

npm install @superuai/superu-webcall

Example Usage (Next.js / React)

⚠️ Security Warning: The example below demonstrates generating a token directly from the frontend for simplicity. In a production environment, you must never expose your superU-Api-Key in the frontend. Token generation should always be handled by your backend server. The frontend should call your backend endpoint, which in turn calls the SuperU API to generate the token and returns it to the client.

Here's an example of how to implement the CallManager in a React application (e.g., Next.js App Router).

"use client"; // Required if you are using Next.js App Router (app/ directory)

import React, { useState, useRef, useEffect } from 'react';
import { CallManager, TranscriptItem } from '@superuai/superu-webcall';
import axios from 'axios';

interface CallDetails {
  token: string | null;
  call_uuid: string | null;
}

export default function SuperUCallPage() {
  const [isCalling, setIsCalling] = useState(false);
  const [transcripts, setTranscripts] = useState<TranscriptItem[]>([]);
  const [speaker, setSpeaker] = useState<"assistant" | "user" | null>(null);
  const [error, setError] = useState<string | null>(null);
  const agent_id = "17daf828-8982-47ee-b93a-6683ff760683";
  const token_backend = "https://voip-middlware.superu.ai";
  
  // Keep a reference to the manager so we can disconnect it later without losing it across re-renders
  const managerRef = useRef<CallManager | null>(null);

  const startCall = async () => {
    try {
      setIsCalling(true);
      setError(null);

      // ⚠️ SECURITY WARNING: This is for demonstration purposes only!
      // In production, do NOT make this request from the frontend, as it exposes your API key.
      // Instead, call your own backend endpoint, which will then make this request to SuperU securely.
      const response = await axios.post(
        `${token_backend}/generate-token-for-participant`,
        {
          agent_id: agent_id,
          variable_values: {
            "customer_name" : "Paras"
          }
        },
        {
          headers: {
            "superU-Api-Key" : "YOUR_SUPERU_API_KEY" // Replace with your actual API key securely
          },
        },
      );

      const token = response.data.token;
      const call_uuid = response.data.call_uuid;
      
      // 1. Initialize the CallManager
      // Pass your config object as the first argument, and your callback listeners as the second
      const manager = new CallManager(
        { token: token, call_uuid: call_uuid },
        {
          onDisconnect: () => {
            // Reset the UI when the call ends
            setIsCalling(false);
            setSpeaker(null);
          },
          onError: (err) => {
            console.error("Call encountered an error:", err);
            setError(err.message || "Something went wrong.");
            setIsCalling(false);
          }
        }
      );

      managerRef.current = manager;

      // 2. Start the call! 
      // (This automatically fetches the token and connects to the LiveKit room)
      await manager.startCall();

    } catch (err: any) {
      console.error("Failed to start the call:", err);
      setError(err.message || "Failed to connect.");
      setIsCalling(false);
    }
  };

  const endCall = () => {
    if (managerRef.current) {
      managerRef.current.disconnect();
      managerRef.current = null;
    }
  };

  // 3. Always clean up when the component unmounts (user navigates away)
  useEffect(() => {
    return () => {
      endCall();
    };
  }, []);

  return (
    <div className="p-8 max-w-2xl mx-auto font-sans">
      <h1 className="text-3xl font-bold mb-6">Voice AI Agent</h1>
      
      {error && (
        <div className="bg-red-100 text-red-700 p-3 rounded mb-4">
          <strong>Error:</strong> {error}
        </div>
      )}

      {/* Connection Controls */}
      <div className="mb-6">
        {!isCalling ? (
          <button 
            onClick={startCall}
            className="bg-blue-600 hover:bg-blue-700 text-white font-semibold px-6 py-2 rounded shadow transition-colors"
          >
            Start Call
          </button>
        ) : (
          <button 
            onClick={endCall}
            className="bg-red-500 hover:bg-red-600 text-white font-semibold px-6 py-2 rounded shadow transition-colors"
          >
            End Call
          </button>
        )}
      </div>
    </div>
  );
}

Setup & Implementation Details

1. Authentication: Obtain your token and call UUID securely from your backend (e.g., generate-token-for-participant endpoint). Never expose your secret API keys in the frontend.
2. Initialization: Instantiate the CallManager with the token and call_uuid, along with optional callbacks (onDisconnect, onError, etc.).
3. Connecting: Call manager.startCall() to initiate the connection.
4. Cleanup: Always ensure to call manager.disconnect() when the component unmounts or when the user manually ends the call to prevent memory leaks and dangling connections.