Connect a voice agent with a secure backend-to-frontend session flow.

Call the session endpoint from your backend service. Send the API key as a request header, and include the agent ID as the required JSON field.

POST https://api.oshara.ai/api/agents/agent-session/
x-api-key: sk_...
Content-Type: application/json

{
  "agent": "agent_id",
  "language": "en",
  "system_prompt": "...",
  "greeting": "...",
  "reference_audio_url": "..."
}

Session response

After the backend creates the session, return only the credentials needed by the frontend. The token authorizes the room connection, and the LiveKit URL tells the client where to connect.

{
  "success": true,
  "message": "Request successful",
  "data": {
    "token": "eyJ...",
    "livekit_url": "wss://audio-inference.oshara.ai",
    "room_name": "unique_room_id"
  }
}

Install `livekit-client` in the frontend app and connect using the credentials returned by your backend. The same room handles both the spoken audio track and a text-chat channel — publish user messages on the `voice.user_text` topic and listen for agent replies on `voice.reply`.

import { Room, RoomEvent, Track } from "livekit-client";

type AgentSession = {
  token: string;
  livekit_url: string;
  room_name?: string;
};

type ChatMessage = {
  role: "user" | "assistant";
  text: string;
};

// The agent echoes typed messages back on "voice.reply" with
// type: "user_text" — the same shape it uses for STT transcripts of
// spoken input. We track texts the user just typed so we can render them
// optimistically and skip the matching echo when it arrives.
const pendingUserTextsByRoom = new WeakMap<Room, string[]>();

async function getAgentSession(agentId: string): Promise<AgentSession> {
  const response = await fetch("/api/voice-agent/session", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      agent: agentId,
      language: "en",
      system_prompt: "...",
      greeting: "...",
      reference_audio_url: "...",
    }),
  });

  if (!response.ok) {
    const message = await response.text();
    throw new Error(message || "Failed to create voice-agent session");
  }

  const payload = await response.json();
  return payload.data as AgentSession;
}

export async function startVoiceAgentCall(
  agentId: string,
  onMessage?: (message: ChatMessage) => void,
) {
  const room = new Room({
    adaptiveStream: true,
    dynacast: true,
  });
  pendingUserTextsByRoom.set(room, []);

  room.on(RoomEvent.Connected, () => {
    console.log("Connected to voice agent room");
  });

  room.on(RoomEvent.Disconnected, () => {
    pendingUserTextsByRoom.delete(room);
    console.log("Disconnected from room");
  });

  // Subscribe to the agent's spoken audio track.
  room.on(RoomEvent.TrackSubscribed, (track, publication, participant) => {
    if (track.kind === Track.Kind.Audio) {
      const element = track.attach();
      element.autoplay = true;
      document.body.appendChild(element);
      console.log("Subscribed to audio track from", participant.identity);
    }
  });

  // Receive agent replies and STT transcripts on the "voice.reply" topic.
  room.on(RoomEvent.DataReceived, (payload, _participant, _kind, topic) => {
    if (topic !== "voice.reply") return;

    try {
      const data = JSON.parse(new TextDecoder().decode(payload));
      const text = (data.text || data.message || "").trim();
      if (!text) return;

      // Drop echoes of messages the user just typed (already rendered).
      if (data.type === "user_text") {
        const pending = pendingUserTextsByRoom.get(room);
        if (pending) {
          const index = pending.indexOf(text);
          if (index !== -1) {
            pending.splice(index, 1);
            return;
          }
        }
      }

      onMessage?.({
        role: data.type === "user_text" ? "user" : "assistant",
        text,
      });
    } catch {
      // Ignore unparseable data frames.
    }
  });

  try {
    const session = await getAgentSession(agentId);

    if (!session.token || !session.livekit_url) {
      throw new Error("Session response is missing token or livekit_url");
    }

    await room.connect(session.livekit_url, session.token, {
      autoSubscribe: true,
    });

    await room.localParticipant.setMicrophoneEnabled(true);

    return room;
  } catch (error) {
    pendingUserTextsByRoom.delete(room);
    room.disconnect();
    throw error;
  }
}

// Send a user-typed message into the live agent session. Render the
// message in your UI immediately after calling this — the matching echo
// from the agent will be deduped by the DataReceived handler above.
export async function sendTextMessage(room: Room, text: string) {
  const trimmed = text.trim();
  if (!trimmed) return;

  pendingUserTextsByRoom.get(room)?.push(trimmed);

  await room.localParticipant.publishData(
    new TextEncoder().encode(
      JSON.stringify({
        type: "user_text",
        text: trimmed,
      }),
    ),
    {
      reliable: true,
      topic: "voice.user_text",
    },
  );
}

export async function endVoiceAgentCall(room: Room | null) {
  if (!room) return;
  pendingUserTextsByRoom.delete(room);
  await room.localParticipant.setMicrophoneEnabled(false);
  room.disconnect();
}