Skip to main content
Site with custom session
Running sessions requires careful handling of two aspects:
  • [Back-End] Starting the session using the specified avatar and agent.
  • [Front-End] Connecting to the session and managing real-time interactions.

​
Starting a session

This must be done from the back-end.
Start Session
import {
Equos,
type CreateEquosSessionResponse,
type EquosSession,
} from "@equos/node-sdk";

const client = Equos.client(process.env.EQUOS_API_KEY!);

const session: CreateEquosSessionResponse = await client.sessions.create({
name: "Translation session",
client: "user...", // Optional: your end-user identifier, use full for resource segmentation.
agent: { id: process.env.EQUOS_AGENT_ID! },
avatar: { id: process.env.EQUOS_AVATAR_ID! },
consumerIdentity: {
    name: "Your user name",
    identity: "your-user-id",
},
});

console.log("Session ID:", session.session.id);
console.log("Session Status:", session.session.status);
console.log("Session Consumer AccessToken:", session.consumerAccessToken);
This will allow you to start a session with your chosen agent and avatar. It will return a response like this: 
{
    "session": {
        "id": "...",
        "status": "starting",
    },
    "consumerAccessToken": "..."
}
​
session
EquosSession
required
The session object containing details about the created session.
​
consumerAccessToken
string
required
The access token used by the front-end to connect to the session.
See all available options in the Start Session Endpoint in the API Reference.
For faster session start up times, we encourage you creating the agent and the avatar beforehand.

​
Joining a session

This is done in the front end. After creating the session and fetching the consumerAccessToken, you can connect to the session.
Equos uses Livekit for real-time and low-latency audio/video streaming. They provide various UI toolkits and SDKs we recommend you using.
Here is an example using the Livekit React SDK: 
"use client";

import { useMemo, useState } from "react";
import { LiveKitRoom } from "@livekit/components-react";

import "@livekit/components-styles";

import { CreateEquosSessionResponse } from "@equos/node-sdk/dist/types/session.type";
import { RoomRenderer } from "./room-renderer";

export default function Page() {
  const [session, setSession] = useState<CreateEquosSessionResponse | null>(
    null
  );

  const onCreateSession = async () => {
    // Call to your backend to create the session.
    const session = null; // Replace with actual call
    setSession(session);
  };

  const onHangUp = async () => {
    if (session) {
        // Call to your backend to stop the session.
    }
    setSession(null);
  };

  return (
    <>
      <div className="flex gap-4">
        <div className="mx-auto flex flex-1 flex-col items-center gap-8 rounded-xl p-8">
          {
            <>
              <div className="relative flex aspect-video w-full items-center justify-center">
                <div className="z-10 flex flex-col items-center gap-8">
                  <span className="text-4xl font-bold">Talk to Jeremy</span>
                  <button size="lg" onClick={onCreateSession}>
                    Start Conversation
                  </button>
                </div>
              </div>
            </>
          }
        </div>
      </div>
      {session && (
        <aside className="fixed bottom-0 left-0 top-0 z-50 flex w-full items-center justify-center bg-black/75">
          <section className="max-w-screen aspect-square h-[512px] max-h-screen w-fit overflow-hidden rounded-xl bg-background">
            <LiveKitRoom
              serverUrl={session.session.host.serverUrl}
              token={session.consumerAccessToken}
              audio={true} // We want the user to be able to speak with the microphone.
              video={false} // We don't need the video of the user.
            >
              <RoomRenderer
                onStop={onHangUp}
                onClose={async () => setSession(null)}
                avatarIdentity={session.session.avatar.identity}
                avatarName={session.session.avatar.name}
              />
            </LiveKitRoom>
          </section>
        </aside>
      )}
    </>
  );
}
This code uses tailwindcss for styling and assumes you have a backend endpoint to create and stop sessions. Adjust the code to fit your front-end framework and design system.
This code is not complete and is provided as a starting point. Check out our NextJS end-to-end implementation example on GitHub for a full working example.

​
Ending a session

This must be done from the back-end.
Run a session
import {
Equos,
type EquosSession,
} from "@equos/node-sdk";

const client = Equos.client(process.env.EQUOS_API_KEY!);

const ended: EquosSession = await client.sessions.stop("<session id>");
console.log("Ended Session Status:", ended.status);
Session duration (and billing) is calculated using session startedAt and endedAt timestamps.
Make sure to call the “end session” endpoint not matter what happens. It will set the endedAt field right away. Not ending the session will result in longer billing times as the session will remain active until it times out.
That’s it! 🎉 You can now safely run low-latency sessions with custom agents and avatars.

Need a full example?

Check our NextJs integration example on GitHub.
⌘I