Web Calls

User clicks "Talk to AI"
        ↓
Your backend → POST https://agent-api.hmsovereign.com/v1/web-calls (Bearer <org_api_key>)
        ↓
HMS validates key, creates voice room, dispatches agent → returns { token, server_url }
        ↓
Your backend passes token + server_url to the browser
        ↓
Browser connects via WebRTC (microphone audio) using the token
        ↓
AI agent picks up → full STT → LLM → TTS pipeline
        ↓
Call ends → summary, transcript, credits deducted, webhook fired

POST https://agent-api.hmsovereign.com/v1/web-calls

{
  "assistant_id": "17a0cb75-fa09-4bdd-9a44-92a70d829c88"
}

{
  "assistant_id": "17a0cb75-fa09-4bdd-9a44-92a70d829c88",
  "assistant_override": {
    "first_message": "Custom greeting!",
    "llm_config": {
      "messages": [{ "role": "system", "content": "You are a sales agent." }]
    }
  }
}

{
  "assistant": {
    "stt_config": { "provider": "deepgram", "model": "nova-3", "language": "en" },
    "llm_config": {
      "provider": "openai",
      "model": "gpt-4.1-mini",
      "messages": [{ "role": "system", "content": "You are a helpful assistant." }]
    },
    "tts_config": { "provider": "elevenlabs", "voice_id": "your-voice-id" },
    "first_message": "Hello! How can I help you?"
  }
}

{
  "success": true,
  "call_id": "3f2a1b4c-5d6e-7f8a-9b0c-1d2e3f4a5b6c",
  "room_name": "web-3f2a1b4c",
  "token": "<jwt>",
  "server_url": "wss://rtc.hmsovereign.com"
}

"use client";

import { useEffect, useRef, useState } from "react";
import { useRoomContext } from "@livekit/components-react";

interface TranscriptEntry {
  id: string;
  role: "user" | "agent";
  text: string;
  isFinal: boolean;
}

export function LiveTranscript() {
  const room = useRoomContext();
  const [entries, setEntries] = useState<TranscriptEntry[]>([]);
  const scrollRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const unregister = room.registerTextStreamHandler(
      "lk.transcription",
      async (reader, participantInfo) => {
        const text = await reader.readAll();
        const attrs = reader.info.attributes;
        const isFinal = attrs["lk.transcription_final"] === "true";
        const segmentId = attrs["lk.segment_id"] ?? reader.info.id;

        const isUser = participantInfo.identity === room.localParticipant.identity;
        const role = isUser ? "user" : "agent";

        setEntries((prev) => {
          const existing = prev.findIndex((e) => e.id === segmentId);
          const entry: TranscriptEntry = { id: segmentId, role, text, isFinal };
          if (existing >= 0) {
            const updated = [...prev];
            updated[existing] = entry;
            return updated;
          }
          return [...prev, entry];
        });
      }
    );

    return () => { unregister?.(); };
  }, [room]);

  useEffect(() => {
    scrollRef.current?.scrollTo(0, scrollRef.current.scrollHeight);
  }, [entries]);

  return (
    <div ref={scrollRef} style={{ maxHeight: 300, overflowY: "auto" }}>
      {entries.map((entry) => (
        <div key={entry.id} style={{ opacity: entry.isFinal ? 1 : 0.5 }}>
          <strong>{entry.role === "agent" ? "Agent" : "You"}:</strong> {entry.text}
        </div>
      ))}
    </div>
  );
}

<LiveKitRoom token={session.token} serverUrl={session.server_url} connect audio onDisconnected={endCall}>
  <CallInterface onHangUp={endCall} />
  <LiveTranscript />
  <RoomAudioRenderer />
</LiveKitRoom>

<LiveKitRoom
  token={session.token}
  serverUrl={session.server_url}
  connect={true}
  audio={true}
  video={false}
  onDisconnected={endCall}
  onError={(err) => {
    // MediaDeviceFailure is thrown when microphone access is denied
    setError("Microphone access was denied. Please allow microphone access and try again.");
    endCall();
  }}
>

{
  "message": {
    "type": "status-update",
    "status": "in-progress",
    "call": {
      "id": "3f2a1b4c-...",
      "type": "web_call",
      "status": "in-progress"
    }
  }
}

{
  "message": {
    "type": "end-of-call-report",
    "call": {
      "id": "3f2a1b4c-...",
      "type": "web_call",
      "status": "ended"
    },
    "endedReason": "user_hangup",
    "durationSeconds": 47,
    "summary": "The user asked about pricing...",
    "transcript": [ "..." ]
  }
}