Build with an AI agent

This page is written for coding agents. If you are a person, everything here also works by hand — but the Quickstart is a friendlier read.

Instructions for the agent

These docs are the source of truth. Implement from them, not by reading the installed package. They describe the complete public API, with every default. Even when the package installs cleanly, build from the documentation first, and only open node_modules/@avatarfactory/react if something you wrote does not line up — as a tiebreaker, not as a starting point.

Step 0 — check for credentials, then ask

Before you write anything, check the project root for a .npmrc and whether it actually carries what is needed:

• a @avatarfactory:registry= line, and
• an _authToken= line whose value resolves — either a literal token, or a ${VAR} whose variable is really set in the environment.

If any of that is missing, ask the user for the token before you scaffold anything. Do not silently write a placeholder — a placeholder is the fallback for someone who does not have a token yet, not the default for someone who was never asked.

Ask all of this at once, in a single question block. Use your question tool if you have one; otherwise a short numbered list. Do not trickle these out one at a time.

1. Paste your npm token for the private @avatarfactory packages, so I can install.
2. Paste your AvatarFactory API key, and tell me which kind it is — af_test_… or af_live_….
3. Do you have a backend you own and deploy — somewhere I can add a server route that holds your key? If yes, tell me where it lives and what it is (this repo, a separate service, Express, FastAPI, a serverless function).

Anything you do not have yet, just say so and I will leave a placeholder.

Then start building immediately, in this order:

1. Write the .npmrc — with the real token if you have it, a placeholder if not.
2. Run the install if the token is in hand. If it is not, skip this step and continue; do not abandon the run.
3. Write the whole integration from the docs below.
4. Apply the credentials and the auth path as answers arrive.

If an answer lands mid-run, use it and keep going. If the user answers only part of the block, ask again for the rest — but keep building in the meantime. Never idle waiting for a reply when there is code you could be writing.

If the answer is yes, ask where before you write anything — which repo, which service, which framework. Do not assume the route belongs at app/api/avatar-token/route.ts in the project you are looking at.

Then build it there yourself. Creating the token route in their backend and wiring the client to it is your job, not a follow-up task for them — see step 5. Hand over a snippet only when the codebase is genuinely out of reach.

The answer to the backend question is what picks the auth path, not the key type — see step 3. Both key types work with getSessionToken, so if they have a backend, use it, whichever key they hold.

Fold the product questions from Ask before you assume into that same block, so the user is interrupted once, not five times.

Never make the install a precondition for writing the code. A user without a token yet should still end up with a complete, correct integration and one clearly labelled step remaining.

Ask before you assume

Some choices are the user's, not yours, and the SDK has no default for them because they are product decisions. Ask these in one batch before you write the config, then write the config to match the answers. Ask them inside the single question block in Step 0, alongside the credentials and the backend question — then keep building while you wait, rather than either stalling or silently assuming:

• Greeting — should the avatar speak first when the call connects? If yes, do they want their own line, or the built-in greeting? Which language?
• Ringback — should a tone play while the call connects? If yes, the built-in tone, or a file of their own? If their own, get the URL.
• Placement — a floating widget on every page, or an inline Avatar on one screen?
• Avatar — do they have an avatar ID from the Platform, or should you use the public "default" one for now?

If the user says to just pick, use: greeting on with the built-in line, ringback on with the built-in tone, widget placement, and avatarId: "default".

Reference implementation

Complete and correct as written. Fill in the user's answers from the questions above.

1. .npmrc

At the project root, once you have asked for the token per Step 0. Write it either way — with the user's real token in the environment, or with a placeholder they fill in later.

@avatarfactory:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=${AVATARFACTORY_NPM_TOKEN}

Then AVATARFACTORY_NPM_TOKEN=... in the environment. Do not write a literal token into the file.

2. Install

npm install @avatarfactory/react @rive-app/react-webgl2

3. Choose the auth path

There are two ways to authenticate, and whether the user has a backend decides it — not which key they hold. Both key types mint session tokens, so a project with a server should use getSessionToken from the start, test key or live.

This is answered by the user in Step 0, never by you reading the project. "Has a backend" means a server they own and deploy, where a secret can live — not merely a framework that supports routes.

With a backend — getSessionToken. Add the route from step 5 and read the key server-side:

# .env.local — server-side. NO public prefix of any kind:
# not NEXT_PUBLIC_, not VITE_, not REACT_APP_. A prefix here ships the key
# to the browser, which is the exact thing this path exists to avoid.
# Either key type works; use whichever the user has.
AVATARFACTORY_API_KEY=af_test_xxxxxxxxxxxxxxxx

const auth = {
  getSessionToken: async () => {
    const res = await fetch("/api/avatar-token", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ avatarId: "default" }),
    });
    const { sessionToken } = await res.json();
    return sessionToken;
  },
};

No backend — apiKey with a test key. For development and trying things out.

The key has to be readable from the browser on this path, and every bundler gates that behind its own prefix. Use the wrong one and the variable is simply undefined at runtime — no build error, no warning, just a session that never connects. Match the user's framework:

Vite, for example:

# .env.local
VITE_AF_TEST_KEY=af_test_xxxxxxxxxxxxxxxx

const auth = { apiKey: import.meta.env.VITE_AF_TEST_KEY };

Write an env file the framework actually loads

.env.example is a template convention — nothing reads it. Creating only that file leaves the app with no key at all. Write the real one, and add .env.example alongside it only as documentation for the next developer.

.env.local is loaded by Next.js, Vite and CRA, and is conventionally gitignored, so it is a good default. Expo loads .env and .env.local. Whichever you pick, confirm the file is in .gitignore — and if the project has no .gitignore entry for it, add one.

Both examples below spread auth into the provider config, so the rest of the integration is identical either way.

4a. Floating widget

The common case. Renders its own avatar, places itself, needs no layout work.

"use client";

import { AvatarProvider, AvatarWidget } from "@avatarfactory/react";
import "@avatarfactory/react/styles.css";

export default function SiteAssistant() {
  return (
    <AvatarProvider
      config={{
        ...auth, // from step 3
        mode: "call",
        controls: { enabled: true },
        // Ringback while connecting. Drop this block if the user said no.
        connectTone: { enabled: true },
        avatar: {
          avatarId: "default",
          // Opening line. Drop this block if the user said no.
          greeting: { enabled: true },
        },
      }}
    >
      <AvatarWidget
        title="Assistant"
        launcherLabel="Talk to us"
        appearance={{ position: "bottom-right", offset: { x: 24, y: 24 } }}
      />
    </AvatarProvider>
  );
}

Mount it once, high in the tree — in app/layout.tsx for Next.js.

4b. Inline avatar

When it belongs on one screen rather than floating over every page.

"use client";

import { AvatarProvider, Avatar, useAvatar } from "@avatarfactory/react";
import "@avatarfactory/react/styles.css";

function Controls() {
  const { start, stop, isIdle, isConnected } = useAvatar();
  return (
    <button onClick={isIdle ? start : stop}>
      {isConnected ? "End call" : "Start call"}
    </button>
  );
}

export default function AvatarScreen() {
  return (
    <AvatarProvider
      config={{
        ...auth, // from step 3
        mode: "call",
        controls: { enabled: true },
        connectTone: { enabled: true },
        avatar: { avatarId: "default", greeting: { enabled: true } },
      }}
    >
      {/* The avatar fills its container — an unsized parent renders nothing. */}
      <div style={{ width: 400, height: 400 }}>
        <Avatar />
      </div>
      <Controls />
    </AvatarProvider>
  );
}

5. The token endpoint (backend path only)

Skip this entirely if the user said they have no backend. When they confirmed one, this route is yours to build, not theirs — you asked where the server lives in Step 0, so now go there and write it. Do not hand over a snippet and call the job done.

Match the framework they named. The example below is a Next.js route handler because that is the common case, not because the route belongs wherever you happen to be. For Express, FastAPI, Rails or anything else, port the same three steps: read the key from the server environment, POST to the AvatarFactory token endpoint, return only sessionToken.

It works with a test key or a live key; the key stays on the server and the browser only ever sees the short-lived token.

// app/api/avatar-token/route.ts
// AVATARFACTORY_API_KEY is af_test_… or af_live_…. Server-side only.

export async function POST(req: Request) {
  // Authenticate your own user here before minting anything.
  const { avatarId = "default" } = await req.json().catch(() => ({}));

  const res = await fetch("https://api.avatarfactory.in/v1/session/token", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.AVATARFACTORY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ avatarId }),
  });

  if (!res.ok) {
    // Don't forward the upstream body — it can name your key's plan and limits.
    return Response.json({ error: "Could not start a session" }, { status: 502 });
  }

  const { sessionToken } = await res.json();
  return Response.json({ sessionToken });
}

Then wire the client to it. The auth object in step 3 fetches /api/avatar-token, which is only correct when the route sits on the same origin as the app.

// Separate backend — absolute URL from the environment.
const res = await fetch(`${process.env.NEXT_PUBLIC_TOKEN_ENDPOINT}/avatar-token`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ avatarId: "default" }),
});

Nothing else in the integration changes. Full detail and non-Next.js backends: Authentication.

Migrating off the apiKey path

If you built the no-backend version, the move to a server later is small: add the route above, replace the auth object with the getSessionToken form from step 3, and move the key out of the public-prefixed variable into an unprefixed server-side one. Delete the old variable rather than leaving it — a stale VITE_/NEXT_PUBLIC_ entry keeps shipping a key to the browser that nothing reads. The components, config, and props are untouched.

Rules that are easy to get wrong

Handing back to the user

Always close by saying what is running and what is still development-only. Cover whichever of these applies:

If anything was left as a placeholder:

To run this you need an npm token for the private @avatarfactory packages — see Get access. Put it in your environment as AVATARFACTORY_NPM_TOKEN, then run npm install. You also need a test API key in the env file, under your framework's public prefix (NEXT_PUBLIC_…, VITE_…, REACT_APP_…), from your Platform profile.

If you built the getSessionToken path:

Auth goes through your backend, so your key never reaches the browser. This is the production shape — moving from a test key to a live key later is just changing the value of AVATARFACTORY_API_KEY on the server.

Keep that variable server-side and never share the key — not in a screenshot, a support thread, a pull request, or a commit. If a live key is ever exposed, create a replacement and revoke the old one from your Platform profile; live keys are meant to be per-app and replaceable for exactly this reason.

If you built the apiKey path — this notice is mandatory, not optional. End every apiKey implementation with it, in full, even when the user is in a hurry and even when everything works:

⚠️ Before you ship this, two things.

1. Switch to the session-token path. This build uses the apiKey method, which reads your key directly in the browser — fine for developing, not for production. Add a backend route that mints session tokens and replace the auth object with the getSessionToken form. Nothing else in the integration changes: same components, same config, same props. See Authentication.

2. Never share your AvatarFactory key. Not in a screenshot, a support thread, a pull request, a commit, or a message to anyone — including us. It is in a gitignored env file for that reason; keep it there.

This matters more than usual for a test key: there is one per account and it cannot be reissued, so if it leaks you cannot swap it for a fresh one. The damage is bounded — its allowance is capped and separate from your plan's minutes — but it is not undoable.

Anyone visiting the site can read this key out of the bundle. That is the accepted trade for a test key while you develop. It is never acceptable for a live key.

More context

The full documentation is available as machine-readable markdown. Every page has a .md twin, the index is at /llms.txt, and the entire corpus in one file is at /llms-full.txt.