SDK Access

next-virtual is a NextJS client SDK that offers a collection of React UI components to easily integrate with VIRTUAL to spawn 3D AI character with messaging feature.


  1. Integration with VIRTUAL: Integrate conversational AI 3D models into your NextJS applications by utilizing the customizable component.

  2. Customizable Components and Hooks: next-virtual provides a customizable UI component to render animated 3D AI character for you. For complete customizability, you can use the useVirtualAI hook to build your own components that integrate with VIRTUAL.

  3. Managed Infrastucture: Conversation storing, memory, databases, model hostings and other infrastructure requirements are managed by Virtual Protocol.

  4. Model Inference Points: API-based inference points allow applications to plug and play our models for usage.


Once you have subscribed to the characters, you will receive an email with the license key.

To install next-virtual in your React project, follow these simple steps:

Step 1: Install the Package

npm install next-virtual --save


yarn add next-virtual

Step 2: Obtain Your API Key

Follow Build with Virtual to obtain your first API key.

Step 3: Implement initAccessToken function

This function communicates with your access token API and returns an VIRTUAL-specific access token.

Sample implementation:

// This function fetches runner access token and keep in cache
export const initAccessToken = async (virtualId: number) => {
  if (!virtualId) return "";
  // runner token by bot is saved as runnerToken<virtualId> in localStorage
  let cachedRunnerToken = localStorage.getItem(`runnerToken${virtualId}`) ?? "";
  // Fetch a new runner token if expired
  if (!cachedRunnerToken || !validateJwt(cachedRunnerToken)) {
    // Get runner token via dapp server
    const accessToken = localStorage.getItem("accessToken");
    if (!accessToken) return "";
    const resp = await fetch(
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${accessToken}`,
        body: JSON.stringify({
          virtualId: virtualId,
    const respJson = await resp.json();
    cachedRunnerToken = respJson.runnerToken ?? "";
    localStorage.setItem(`runnerToken${virtualId}`, cachedRunnerToken);
  return cachedRunnerToken;

Step 4: Put the CharacterRoom component

Now you can start using the UI components provided by react-character-ai in your React components.

import { CharacterRoom } from "next-virtual";

return (
    virtualName="Virtual Name"
    virtualId={1} // unique virtual id in number / string

If you prefer implementing own components, use the useVirtualAI hook as follows.

const { modelUrl, createPrompt, virtualConfig, runnerUrl } = useVirtualAI({

Next step

To continue from here, you can either:

  • Check out our Virtuals and start consuming them.

  • Read our API References to understand our API Endpoints.

  • Learn more about how our SDK works.

Last updated