# Create a new Equos Brain.
Source: https://docs.equos.ai/api-reference/brain/create-a-new-equos-brain

https://api.equos.ai/docs/v3-json post /v3/brains



# Delete an Equos Brain. This action is irreversible.
Source: https://docs.equos.ai/api-reference/brain/delete-an-equos-brain-this-action-is-irreversible

https://api.equos.ai/docs/v3-json delete /v3/brains/{id}



# Get Equos Brain by ID.
Source: https://docs.equos.ai/api-reference/brain/get-equos-brain-by-id

https://api.equos.ai/docs/v3-json get /v3/brains/{id}



# List Equos Brains.
Source: https://docs.equos.ai/api-reference/brain/list-equos-brains

https://api.equos.ai/docs/v3-json get /v3/brains



# Update an Equos Brain.
Source: https://docs.equos.ai/api-reference/brain/update-an-equos-brain

https://api.equos.ai/docs/v3-json patch /v3/brains/{id}



# Create a new Equos Character.
Source: https://docs.equos.ai/api-reference/character/create-a-new-equos-character

https://api.equos.ai/docs/v3-json post /v3/characters



# Delete an Equos Character. This action is irreversible.
Source: https://docs.equos.ai/api-reference/character/delete-an-equos-character-this-action-is-irreversible

https://api.equos.ai/docs/v3-json delete /v3/characters/{id}



# Get Equos Character by ID.
Source: https://docs.equos.ai/api-reference/character/get-equos-character-by-id

https://api.equos.ai/docs/v3-json get /v3/characters/{id}



# List Equos Characters.
Source: https://docs.equos.ai/api-reference/character/list-equos-characters

https://api.equos.ai/docs/v3-json get /v3/characters



# Update character properties.
Source: https://docs.equos.ai/api-reference/character/update-character-properties

https://api.equos.ai/docs/v3-json put /v3/characters/{id}



# Get Equos conversation by id.
Source: https://docs.equos.ai/api-reference/conversation/get-equos-conversation-by-id

https://api.equos.ai/docs/v3-json get /v3/conversations/{id}



# List Equos conversations.
Source: https://docs.equos.ai/api-reference/conversation/list-equos-conversations

https://api.equos.ai/docs/v3-json get /v3/conversations



# Start an Equos avatar sesssion.
Source: https://docs.equos.ai/api-reference/conversation/start-an-equos-avatar-sesssion

https://api.equos.ai/docs/v3-json post /v3/conversations



# Stop a conversation. Returns null if already stopped or conversation was not found.
Source: https://docs.equos.ai/api-reference/conversation/stop-a-conversation-returns-null-if-already-stopped-or-conversation-was-not-found

https://api.equos.ai/docs/v3-json post /v3/conversations/{id}/stop



# Create a new Equos Face.
Source: https://docs.equos.ai/api-reference/face/create-a-new-equos-face

https://api.equos.ai/docs/v3-json post /v3/faces



# Delete an Equos Face. This action is irreversible.
Source: https://docs.equos.ai/api-reference/face/delete-an-equos-face-this-action-is-irreversible

https://api.equos.ai/docs/v3-json delete /v3/faces/{id}



# Get Equos Face by ID.
Source: https://docs.equos.ai/api-reference/face/get-equos-face-by-id

https://api.equos.ai/docs/v3-json get /v3/faces/{id}



# List Equos Faces.
Source: https://docs.equos.ai/api-reference/face/list-equos-faces

https://api.equos.ai/docs/v3-json get /v3/faces



# Health check endpoint
Source: https://docs.equos.ai/api-reference/health/health-check-endpoint

https://api.equos.ai/docs/v3-json get /v3/health



# Add a document to a Knowledge Base.
Source: https://docs.equos.ai/api-reference/knowledgebase/add-a-document-to-a-knowledge-base

https://api.equos.ai/docs/v3-json post /v3/knowledge-bases/{id}/documents



# Create a new Knowledge Base.
Source: https://docs.equos.ai/api-reference/knowledgebase/create-a-new-knowledge-base

https://api.equos.ai/docs/v3-json post /v3/knowledge-bases



# Delete a document from a Knowledge Base.
Source: https://docs.equos.ai/api-reference/knowledgebase/delete-a-document-from-a-knowledge-base

https://api.equos.ai/docs/v3-json delete /v3/knowledge-bases/{id}/documents/{doc}



# Delete a Knowledge Base. This action is irreversible.
Source: https://docs.equos.ai/api-reference/knowledgebase/delete-a-knowledge-base-this-action-is-irreversible

https://api.equos.ai/docs/v3-json delete /v3/knowledge-bases/{id}



# Get Knowledge Base by ID.
Source: https://docs.equos.ai/api-reference/knowledgebase/get-knowledge-base-by-id

https://api.equos.ai/docs/v3-json get /v3/knowledge-bases/{id}



# Index a document in a Knowledge Base.
Source: https://docs.equos.ai/api-reference/knowledgebase/index-a-document-in-a-knowledge-base

https://api.equos.ai/docs/v3-json patch /v3/knowledge-bases/{id}/documents/{doc}/index



# List Knowledge Bases.
Source: https://docs.equos.ai/api-reference/knowledgebase/list-knowledge-bases

https://api.equos.ai/docs/v3-json get /v3/knowledge-bases



# Get organization freemium usage.
Source: https://docs.equos.ai/api-reference/organization/get-organization-freemium-usage

https://api.equos.ai/docs/v3-json get /v3/organizations/freemium-usage



# Get per-user billing cycle usage.
Source: https://docs.equos.ai/api-reference/organization/get-per-user-billing-cycle-usage

https://api.equos.ai/docs/v3-json get /v3/organizations/user-usage



# Generate a client token for a specific character.
Source: https://docs.equos.ai/api-reference/tokens/generate-a-client-token-for-a-specific-character

https://api.equos.ai/docs/v3-json post /v3/tokens



# Create a new Equos Voice.
Source: https://docs.equos.ai/api-reference/voice/create-a-new-equos-voice

https://api.equos.ai/docs/v3-json post /v3/voices



# Delete an Equos Voice. This action is irreversible.
Source: https://docs.equos.ai/api-reference/voice/delete-an-equos-voice-this-action-is-irreversible

https://api.equos.ai/docs/v3-json delete /v3/voices/{id}



# Get Equos Voice by ID.
Source: https://docs.equos.ai/api-reference/voice/get-equos-voice-by-id

https://api.equos.ai/docs/v3-json get /v3/voices/{id}



# List Equos Voices.
Source: https://docs.equos.ai/api-reference/voice/list-equos-voices

https://api.equos.ai/docs/v3-json get /v3/voices



# Update an Equos Voice.
Source: https://docs.equos.ai/api-reference/voice/update-an-equos-voice

https://api.equos.ai/docs/v3-json patch /v3/voices/{id}



# Introduction
Source: https://docs.equos.ai/index

This is the right place to start. On this page, you will learn about **characters** and the key concepts of running interactive AI experiences with Equos.

<Card title="Already familiar? Start here" icon="rocket" href="/quickstart/setup">
  Create an account and chat with your first character on Equos.
</Card>

## Jump right in

<Columns>
  <Card icon="robot" title="Equos Studio" href="https://studio.equos.ai">Chat with your custom character.</Card>
  <Card icon="github" title="App examples" href="https://github.com/EquosAI/equos-examples">Checkout our app samples.</Card>
  <Card icon="node" title="NodeJS SDK" href="/sdks/nodejs">Build with Equos & NodeJS</Card>
  <Card icon="slack" title="Ask the community" href="https://join.slack.com/t/equosaicommunity/shared_invite/zt-3d8oy19au-jZpsJB0i~gdL0jbDswdzzQ">Any questions? Reach out on Slack</Card>
</Columns>

## Characters

A **character** is a complete interactive AI persona you build on Equos.
It has a visual identity, a voice, a personality, and the knowledge and abilities it needs to hold meaningful conversations.

<Frame>
  <img alt="Setting up a character in the Equos Studio" />
</Frame>

Every character is assembled from six building blocks:

<CardGroup>
  <Card icon="face-smile" title="Face">
    The visual identity of your character. A single image—photo, painting, illustration, or AI-generated—is enough to bring it to life with accurate lip-sync and expression.
  </Card>

  <Card icon="waveform" title="Voice">
    How your character sounds. Pick from a catalog of voices or bring your own via supported TTS providers.
  </Card>

  <Card icon="brain" title="Brain (Prompt)">
    The personality and behavior. Define tone, identity, role, and scope through instructions—your character can be a coach, a tutor, a support rep, or any persona you imagine.
  </Card>

  <Card icon="book" title="Knowledge">
    A knowledge base the character can draw from (RAG). Upload documents so it can answer questions grounded in your own content.
  </Card>

  <Card icon="screwdriver-wrench" title="Tools">
    Actions the character can take—calling APIs, looking up data, triggering workflows—so it can do things, not just talk.
  </Card>

  <Card icon="message" title="First Message">
    The opening line your character speaks when a conversation starts. Sets the tone and guides the user into the experience.
  </Card>
</CardGroup>

Want inspiration? Read how companies are using Equos to build [creative, experiential live AI applications](https://www.equos.ai/blog/the-next-frontier-creative-experiential-live-ai-avatar-applications).

<Card title="Try it now" icon="sparkles" href="/quickstart/setup">
  Talk to your first AI-powered character in minutes.
</Card>


# Backend
Source: https://docs.equos.ai/integration/backend

Create conversations, characters, and knowledge bases from your server using the Node.js or Python SDK.

Your backend is the only place that should hold your Equos API key. It's responsible for:

* Creating **characters**, **knowledge bases**, and other resources
* Starting **conversations** and forwarding the credentials to the client
* Stopping conversations when you're done

Equos offers two backend SDKs—pick whichever fits your stack.

<CardGroup>
  <Card icon="node" title="@equos/node-sdk" href="/sdks/nodejs">NPM package for Node.js (and any JS runtime).</Card>
  <Card icon="python" title="equos" href="/sdks/python">Pip package with sync and async clients.</Card>
</CardGroup>

***

## Start a conversation

The most common backend operation: create a conversation for a given character, and return the credentials the client needs to join.

<CodeGroup>
  ```ts Node.js theme={null}
  import { EquosClient } from "@equos/node-sdk";

  const client = EquosClient.create(process.env.EQUOS_API_KEY!);

  const { conversation, consumerAccessToken } =
    await client.conversations.startConversation({
      createEquosConversationRequest: {
        name: "Demo conversation",
        characterId: process.env.EQUOS_CHARACTER_ID!,
        consumer: { name: "Demo User", identity: "demo-user" },
      },
    });

  // Send these three fields to your client:
  // - conversation.serverUrl        (LiveKit WebSocket URL)
  // - consumerAccessToken            (short-lived JWT)
  // - conversation.character.livekitIdentity
  ```

  ```python Python theme={null}
  import os
  from equos import EquosClient
  from equos.models import CreateEquosConversationRequest, EquosParticipantIdentity

  client = EquosClient(api_key=os.environ["EQUOS_API_KEY"])

  response = client.conversations.start(
      CreateEquosConversationRequest(
          name="Demo conversation",
          character_id=os.environ["EQUOS_CHARACTER_ID"],
          consumer=EquosParticipantIdentity(name="Demo User", identity="demo-user"),
      )
  )

  # Send these three fields to your client:
  # - response.conversation.server_url
  # - response.consumer_access_token
  # - response.conversation.character.livekit_identity
  ```
</CodeGroup>

<Warning>
  Never expose `EQUOS_API_KEY` to the client. Only the `conversation` object and `consumerAccessToken` should cross the wire.
</Warning>

## Stop a conversation

<CodeGroup>
  ```ts Node.js theme={null}
  await client.conversations.stopConversation({ id: conversation.id });
  ```

  ```python Python theme={null}
  client.conversations.stop(response.conversation.id)
  ```
</CodeGroup>

***

## Manage other resources

The same client can create and manage every resource in your organization: **characters**, **knowledge bases**, **voices**, and more. See the SDK pages for the full API surface:

<CardGroup>
  <Card icon="node" title="Node.js SDK reference" href="/sdks/nodejs">Install, client init, full API.</Card>
  <Card icon="python" title="Python SDK reference" href="/sdks/python">Install, client init, sync + async.</Card>
</CardGroup>

***

## Full examples

<CardGroup>
  <Card icon="github" title="Node.js example" href="https://github.com/EquosAI/equos-examples/tree/main/examples/equos-nodejs-integration">
    Complete Node.js project creating characters, knowledge bases, and conversations.
  </Card>

  <Card icon="github" title="Python example" href="https://github.com/EquosAI/equos-examples/tree/main/examples/equos-python-integration">
    Sync and async Python scripts for the same flows.
  </Card>
</CardGroup>

## Next step

Once your backend is returning a conversation payload, wire it up to a client:

<CardGroup>
  <Card icon="browser" title="Web client" href="/integration/web">Connect from a browser using the Browser SDK or React SDK.</Card>
  <Card icon="mobile" title="Native client" href="/integration/native">Connect from iOS or Android using LiveKit.</Card>
</CardGroup>


# Native (iOS & Android)
Source: https://docs.equos.ai/integration/native

Connect from a native mobile app using the LiveKit iOS or Android SDKs.

Equos rooms run on [LiveKit](https://livekit.io), so a native iOS or Android app can join a conversation using the official LiveKit SDKs—no Equos-specific mobile SDK required.

Your backend still creates the conversation the same way ([see Backend](/integration/backend)); the client just uses a different library to connect to the returned room.

<Note>
  Equos doesn't currently ship a dedicated mobile SDK, but the official LiveKit SDKs give you everything you need to render the character's video and send microphone audio.
</Note>

***

## The fields you need

From the backend response, forward these to your mobile app:

* `conversation.serverUrl` — the LiveKit WebSocket URL
* `consumerAccessToken` — the short-lived JWT the user connects with
* `conversation.character.livekitIdentity` — the character's participant identity (useful for filtering remote tracks)

***

## iOS (Swift)

Install the LiveKit Swift SDK:

```
https://github.com/livekit/client-sdk-swift
```

Connect and attach the character's video track:

```swift theme={null}
import LiveKit

let room = Room()
try await room.connect(
    url: conversation.serverUrl,
    token: consumerAccessToken
)

// Enable the user's microphone
try await room.localParticipant.setMicrophone(enabled: true)

// Subscribe to the character's tracks
room.add(delegate: self)

// In RoomDelegate:
func room(_ room: Room, participant: RemoteParticipant,
          didSubscribeTrack publication: RemoteTrackPublication) {
    if participant.identity?.stringValue == conversation.character.livekitIdentity,
       let videoTrack = publication.track as? VideoTrack {
        videoView.track = videoTrack
    }
}
```

<Card icon="book" title="LiveKit iOS docs" href="https://docs.livekit.io/reference/client-sdk-swift/">
  Full reference for the Swift SDK.
</Card>

***

## Android (Kotlin)

Add the LiveKit Android SDK:

```kotlin theme={null}
implementation("io.livekit:livekit-android:<latest>")
```

Connect and render:

```kotlin theme={null}
import io.livekit.android.LiveKit
import io.livekit.android.room.Room

val room = LiveKit.create(applicationContext)

room.connect(
    url = conversation.serverUrl,
    token = consumerAccessToken
)

room.localParticipant.setMicrophoneEnabled(true)

// Attach the character's video track when it arrives
room.events.collect { event ->
    if (event is RoomEvent.TrackSubscribed &&
        event.participant.identity?.value == conversation.character.livekitIdentity) {
        (event.track as? VideoTrack)?.let { videoRenderer.bindTrack(it) }
    }
}
```

<Card icon="book" title="LiveKit Android docs" href="https://docs.livekit.io/reference/client-sdk-android/">
  Full reference for the Android SDK.
</Card>

***

## Tips

<Tip>
  The `consumerAccessToken` is short-lived. Don't cache it—fetch a fresh conversation from your backend each time the user wants to start talking.
</Tip>

<Warning>
  Never ship your Equos API key inside a mobile app. Only your backend should ever see it.
</Warning>


# Overview
Source: https://docs.equos.ai/integration/overview

How to integrate Equos into your own application—backend, web, and native.

Integrating Equos into your application is a three-layer story:

<CardGroup>
  <Card icon="server" title="1. Backend" href="/integration/backend">
    Your server uses the Equos SDK to create characters, knowledge bases, and—most importantly—**conversations**. It holds your API key; clients never do.
  </Card>

  <Card icon="browser" title="2. Web client" href="/integration/web">
    Your frontend takes the response from a conversation creation and connects to the live room. Use **@equos/browser-sdk** (vanilla) or **@equos/react** (React/Next.js).
  </Card>

  <Card icon="mobile" title="3. Native client" href="/integration/native">
    For iOS or Android, use the official **LiveKit** SDKs with the `consumerAccessToken` and `serverUrl` returned by your backend.
  </Card>
</CardGroup>

## The flow

1. Your backend calls `startConversation` with a `characterId` and a consumer identity. Equos spins up a live room and returns:
   * `conversation.serverUrl` — the LiveKit WebSocket URL for the room
   * `consumerAccessToken` — a short-lived JWT the end user uses to join
   * `conversation.character.livekitIdentity` — the identity the character publishes as
2. You forward those fields to your client (web or native).
3. The client connects to the room and starts talking to the character.

<Warning>
  Your **API key** lives on the server only. The client should only ever receive the `conversation` object and the `consumerAccessToken`.
</Warning>

## Working examples

The [equos-examples](https://github.com/EquosAI/equos-examples) repo contains complete, runnable apps for every layer:

<CardGroup>
  <Card icon="github" title="Node.js backend" href="https://github.com/EquosAI/equos-examples/tree/main/examples/equos-nodejs-integration">
    Full backend project with `@equos/node-sdk`.
  </Card>

  <Card icon="github" title="Python backend" href="https://github.com/EquosAI/equos-examples/tree/main/examples/equos-python-integration">
    Sync and async Python with the `equos` package.
  </Card>

  <Card icon="github" title="Vanilla JS frontend" href="https://github.com/EquosAI/equos-examples/tree/main/examples/equos-vanilla-integration">
    Plain HTML + TypeScript using `@equos/browser-sdk`.
  </Card>

  <Card icon="github" title="React frontend" href="https://github.com/EquosAI/equos-examples/tree/main/examples/equos-react-integration">
    Vite + React app using `@equos/react`.
  </Card>

  <Card icon="github" title="Next.js full-stack" href="https://github.com/EquosAI/equos-examples/tree/main/examples/equos-nextjs-integration">
    Next.js 15 with server actions + `@equos/react`.
  </Card>
</CardGroup>


# Web
Source: https://docs.equos.ai/integration/web

Connect a browser to a live conversation using the Equos Browser or React SDKs.

Once your backend has called `startConversation`, the response contains everything your web client needs to join the live room:

* `conversation.serverUrl` — the LiveKit WebSocket URL
* `consumerAccessToken` — the end-user's JWT
* `conversation.character.livekitIdentity` — the character's identity for event wiring

Pick the SDK that matches your stack.

<CardGroup>
  <Card icon="js" title="@equos/browser-sdk" href="#browser-sdk">Vanilla TypeScript/JavaScript. Great for custom UIs or non-React frameworks.</Card>
  <Card icon="react" title="@equos/react" href="#react-sdk">Provider + renderer components for React, Next.js, Remix, etc.</Card>
</CardGroup>

***

## Browser SDK

Install:

```bash theme={null}
npm i @equos/browser-sdk
```

Fetch the conversation credentials from your backend, then hand them to `EquosConversation`:

```ts theme={null}
import { EquosConversation, EquosEvent } from "@equos/browser-sdk";

const video = document.getElementById("character-video") as HTMLVideoElement;

// 1. Get credentials from your backend
const res = await fetch("/api/start-conversation", { method: "POST" });
const { conversation: conv, consumerAccessToken } = await res.json();

// 2. Build the client with the three fields
const conversation = new EquosConversation({
  config: {
    wsUrl: conv.serverUrl,
    token: consumerAccessToken,
    agentIdentity: conv.character.livekitIdentity,
  },
});

// 3. Handle events and connect
conversation.on(EquosEvent.AgentConnected, () => conversation.attach(video));
conversation.on(EquosEvent.Utterance, ({ utterance }) =>
  console.log(utterance.author, utterance.content)
);

await conversation.connect();
```

Common controls:

```ts theme={null}
await conversation.setMicrophoneEnabled(true);   // mic on
conversation.sendText("Hello!");                  // send a text message
await conversation.disconnect();                  // hang up
conversation.detach(video);                       // unbind the <video>
```

<Card icon="github" title="Full vanilla example" href="https://github.com/EquosAI/equos-examples/tree/main/examples/equos-vanilla-integration">
  Plain HTML + TypeScript project using Vite.
</Card>

***

## React SDK

Install:

```bash theme={null}
npm i @equos/react
```

The React SDK wraps the browser SDK in a provider + renderer so you don't have to wire events manually:

```tsx theme={null}
import {
  EquosConversationProvider,
  EquosConversationRenderer,
} from "@equos/react";
import { useState } from "react";

export default function App() {
  const [response, setResponse] = useState(null);

  const start = async () => {
    const res = await fetch("/api/start-conversation", { method: "POST" });
    setResponse(await res.json()); // { conversation, consumerAccessToken }
  };

  if (!response) return <button onClick={start}>Start conversation</button>;

  return (
    <EquosConversationProvider
      conversation={response.conversation}
      accessToken={response.consumerAccessToken}
      autoPublishMic
    >
      <EquosConversationRenderer
        allowMic
        allowCamera
        allowScreenshare
        allowHangUp
        onHangUp={() => setResponse(null)}
      />
    </EquosConversationProvider>
  );
}
```

Inside the provider, a `useEquosConversation()` hook exposes methods like `sendText()` and `sendContext()` for building custom controls.

<Card icon="github" title="Full React example" href="https://github.com/EquosAI/equos-examples/tree/main/examples/equos-react-integration">
  Vite + React app using `<EquosConversationProvider>` and `<EquosConversationRenderer>`.
</Card>

***

## Next.js (full-stack pattern)

Next.js is the canonical full-stack pattern: your API key stays on the server (in a server action or route handler), and only the conversation payload crosses to the client.

**Server action** — `app/actions.ts`:

```ts theme={null}
"use server";
import { equos } from "@/lib/equos"; // server-only EquosClient

export async function startConversationAction() {
  return equos.conversations.startConversation({
    createEquosConversationRequest: {
      name: `nextjs-demo-${Date.now()}`,
      characterId: process.env.EQUOS_CHARACTER_ID!,
      consumer: { name: "Demo User", identity: "demo-user" },
    },
  });
}

export async function stopConversationAction(id: string) {
  await equos.conversations.stopConversation({ id });
}
```

**Client component** — `app/conversation-client.tsx`:

```tsx theme={null}
"use client";
import {
  EquosConversationProvider,
  EquosConversationRenderer,
} from "@equos/react";
import { useState, useTransition } from "react";
import {
  startConversationAction,
  stopConversationAction,
} from "./actions";

export function ConversationClient() {
  const [response, setResponse] = useState(null);
  const [, startTransition] = useTransition();

  const start = () =>
    startTransition(async () =>
      setResponse(await startConversationAction())
    );

  const stop = async () => {
    const id = response.conversation.id;
    setResponse(null);
    await stopConversationAction(id);
  };

  if (!response) return <button onClick={start}>Start conversation</button>;

  return (
    <EquosConversationProvider
      conversation={response.conversation}
      accessToken={response.consumerAccessToken}
      autoPublishMic
    >
      <EquosConversationRenderer
        allowMic
        allowCamera
        allowHangUp
        onHangUp={stop}
      />
    </EquosConversationProvider>
  );
}
```

<Tip>
  Mark your server-side Equos client with `import "server-only"` so Next.js fails the build if anything tries to import the API key into a client bundle.
</Tip>

<Card icon="github" title="Full Next.js example" href="https://github.com/EquosAI/equos-examples/tree/main/examples/equos-nextjs-integration">
  Next.js 15 app with server actions + `@equos/react`.
</Card>

***

## Features

The following features are available in both the Browser SDK and the React SDK.

### Mode switch (text · audio · video)

A conversation can run in one of three modes:

* `EquosMode.Text` — typed messages only, no audio or video
* `EquosMode.Audio` — voice conversation, no video
* `EquosMode.Video` — full video + voice (default)

<CodeGroup>
  ```ts Browser SDK theme={null}
  import { EquosMode, EquosEvent, type EquosModeType } from "@equos/browser-sdk";

  // Change mode at runtime
  conversation.setMode(EquosMode.Audio);

  // React to remote changes
  conversation.on(EquosEvent.ModeChanged, (mode: EquosModeType) => {
    console.log("Mode is now", mode); // "text" | "audio" | "video"
  });
  ```

  ```tsx React SDK theme={null}
  import { EquosMode, type EquosModeType } from "@equos/browser-sdk";
  import { EquosConversationProvider } from "@equos/react";
  import { useState } from "react";

  export function Conversation({ response }) {
    const [mode, setMode] = useState<EquosModeType>(EquosMode.Video);

    return (
      <EquosConversationProvider
        conversation={response.conversation}
        accessToken={response.consumerAccessToken}
        autoPublishMic
        mode={mode}
      >
        <button onClick={() => setMode(EquosMode.Text)}>Text</button>
        <button onClick={() => setMode(EquosMode.Audio)}>Audio</button>
        <button onClick={() => setMode(EquosMode.Video)}>Video</button>
        {/* ... */}
      </EquosConversationProvider>
    );
  }
  ```
</CodeGroup>

<Note>
  In the React SDK, `mode` is a **controlled prop** on `EquosConversationProvider`—update your state and re-render to change it.
</Note>

***

### Send user text

Send a text message from the user to the character—useful for typed input, accessibility, or in `EquosMode.Text` conversations. Behaves like the user spoke the message.

<CodeGroup>
  ```ts Browser SDK theme={null}
  conversation.sendText("What's the refund policy?");
  ```

  ```tsx React SDK theme={null}
  import { useEquosConversation } from "@equos/react";

  function Composer() {
    const { sendText } = useEquosConversation();
    const [value, setValue] = useState("");

    return (
      <form onSubmit={(e) => {
        e.preventDefault();
        const text = value.trim();
        if (!text) return;
        sendText(text);
        setValue("");
      }}>
        <input value={value} onChange={(e) => setValue(e.target.value)} />
        <button type="submit">Send</button>
      </form>
    );
  }
  ```
</CodeGroup>

***

### Send context

Inject **silent context** into the conversation—information the character should know about, but that isn't spoken by the user and doesn't appear as a message. Great for things like:

* Telling the character who the logged-in user is (`"The user's name is Alex, Pro tier, signed up in 2024."`)
* Passing in the current page or screen the user is on
* Feeding live data (cart contents, current order, sensor readings) as the conversation evolves

<CodeGroup>
  ```ts Browser SDK theme={null}
  conversation.sendContext("The user is currently viewing the pricing page.");
  ```

  ```tsx React SDK theme={null}
  import { useEquosConversation } from "@equos/react";

  function PageTracker({ page }) {
    const { sendContext } = useEquosConversation();

    useEffect(() => {
      sendContext(`The user is currently on the ${page} page.`);
    }, [page]);

    return null;
  }
  ```
</CodeGroup>

<Tip>
  Unlike `sendText`, `sendContext` does **not** surface as a user utterance. The character picks it up as background knowledge for its next response.
</Tip>


# On-Device Rendering
Source: https://docs.equos.ai/on-device-rendering

Run Equos characters in real time, directly on the user's phone.

Equos is the only character platform built to render **fully on-device**, in real time, with no compromise on quality.

Our rendering model has been engineered from the ground up to run on consumer mobile hardware—including devices several years old, like the **iPhone 11**—while still delivering the same lifelike lip-sync and expressions you get from the cloud.

***

## Why it matters

<CardGroup>
  <Card icon="gauge-max" title="Zero server cost per frame">
    Video is rendered on the user's device, not streamed from a GPU in the cloud. Your infrastructure bill doesn't grow with each new user.
  </Card>

  <Card icon="users" title="Scale to millions">
    Because every user brings their own compute, you can ship a real-time, video-rich AI experience to millions of concurrent users without provisioning a single GPU.
  </Card>

  <Card icon="bolt" title="Real time, on older hardware">
    Tuned for mobile. Runs smoothly on iPhones going back to the iPhone 11—no high-end chip required.
  </Card>

  <Card icon="wifi-slash" title="Works offline (video)">
    Video rendering doesn't need the network. Pair it with a local voice model to run fully offline, or keep the voice pipeline in the cloud—your choice.
  </Card>
</CardGroup>

***

## What's possible

* **Consumer apps** — ship an animated AI character to every user without a per-user GPU bill.
* **Gaming & social** — real-time NPCs or companions running natively inside a mobile experience.
* **Education & training** — always-available tutors or coaches that work anywhere, even offline.
* **Accessibility** — on-device rendering means lower latency and no network dependency.

***

## Get in touch

On-device rendering is available as a **private SDK**. If you're building a product where server-side rendering won't scale—or where latency and offline support matter—let's talk.

<Card title="Contact us for a demo" icon="envelope" href="https://docs.google.com/forms/d/e/1FAIpQLSdoK7LvORdQf7KOQKvhhlESStJcKc3bDB9HPsEet6LuOmVUfQ/viewform">
  Request early access and a walkthrough of the on-device rendering SDK.
</Card>


# Chat with your character
Source: https://docs.equos.ai/quickstart/chat-with-character

Start a live conversation with your Equos character in a single click.

## Start a conversation

Open any character from your [dashboard](https://studio.equos.ai) and click **Start Chatting** to launch a live conversation.

<Frame>
  <img alt="Character page with the Start Chatting button" />
</Frame>

<Tip>
  No setup required—every character ships ready to talk.
</Tip>

***

## During the conversation

Once the character joins the room, just start speaking. They'll listen, think, and respond in real time.

<Frame>
  <img alt="Live conversation with an Equos character" />
</Frame>

From the in-call controls you can:

* 🎙️ **Mute your mic** to pause the conversation without hanging up
* 📷 **Turn on your camera** and ask the character about what it sees
* 🖥️ **Share your screen** to get help with what's in front of you

<Tip>
  Try sharing your screen or turning on your camera, then ask "what am I looking at?"—your character can see and react in real time.
</Tip>

To end the conversation, click the **Hang Up** button (the big red button).

***

## Usage limits

You can set up a payment method at any time on the [Billing page](https://studio.equos.ai/billing).

<Note>
  * **Freemium users** → Limited to 3-minute conversations and 1 conversation at a time
  * **Pro users** → Up to 2 hours per conversation and 100 concurrent conversations
</Note>

***

## 🚀 You're ready to chat!

With just one click, you can bring your character to life—try it out now!


# Set up your organization
Source: https://docs.equos.ai/quickstart/setup

Get your Equos account up and running in just a few steps.

## Create your account

Go to [studio.equos.ai](https://studio.equos.ai) and log in using one of the following options:

* **Magic Link** (email login)
* **Google**
* **GitHub**

<Frame>
  <img alt="Signing in to the Equos Studio" />
</Frame>

<Note>
  If you choose **Magic Link**, an email will be sent to your inbox.\
  Click the link in that email to log in. If you don’t see it right away, check your spam or promotions folder.
</Note>

<Warning>
  Having trouble signing in? Reach out to our [support team](https://docs.google.com/forms/d/e/1FAIpQLSdoK7LvORdQf7KOQKvhhlESStJcKc3bDB9HPsEet6LuOmVUfQ/viewform).
</Warning>

***

## Onboarding

Once logged in, you'll be redirected to the [onboarding flow](https://studio.equos.ai/getting-started), which walks you through creating your first **character** by picking a **face** and a **voice**.

<Frame>
  <img alt="Equos onboarding flow" />
</Frame>

<Tip>
  The onboarding is optional—you can skip it and create your character later from the dashboard.
</Tip>

***

## Billing setup

To avoid any service interruptions once you reach the free tier limit, head over to the [Billing Page](https://studio.equos.ai/billing) and add a payment method.

***

## 🎉 You’re all set!

Congratulations — your organization is now ready to use Equos!


# Create API Keys
Source: https://docs.equos.ai/recipes/create-api-key

API keys authenticate your requests to the Equos API. Learn how to create, manage, and secure them.

<Warning>
  API keys are **developer credentials**. If you're not a developer, you probably don't need to create one.
</Warning>

This guide explains how to create and manage API keys in the Equos Studio.

<Card title="Don't have an account yet?" href="/quickstart/setup" icon="rocket">
  Follow the setup guide to create your Equos account and organization.
</Card>

<Frame>
  <img alt="API Keys page in the Equos Studio" />
</Frame>

<Steps>
  <Step title="Open the API Keys page">
    Go to [studio.equos.ai/api-keys](https://studio.equos.ai/api-keys).
  </Step>

  <Step title="Create a new key">
    Click the **+** button in the top-right corner, fill in the form, and submit.
  </Step>

  <Step title="Save your key">
    Copy the generated key and store it somewhere safe. You won't be able to view it again.
  </Step>
</Steps>

***

## Important

<Danger>
  **Never expose your API key in the browser or any client-side code.** Keys grant full access to your organization and must only be used from a secure backend.
</Danger>

<Warning>
  **The key is only shown once.** Equos stores a hash of the key, not the key itself—if you lose it, you'll need to create a new one.
</Warning>

<Tip>
  If a key is ever compromised, disable it immediately from the API Keys page and create a new one.
</Tip>

***

### Next Steps

<Columns>
  <Card title="Node.js SDK" icon="node" href="/sdks/nodejs">
    Build faster with our official Node.js SDK.
  </Card>

  <Card title="API Reference" icon="server" href="/api-reference/health/health-check-endpoint">
    Explore all endpoints in the API reference.
  </Card>
</Columns>


# Create a Character
Source: https://docs.equos.ai/recipes/create-character

Build a character from scratch—pick a face, a voice, and define how it thinks, speaks, and acts.

A **character** is a complete interactive AI persona made of six building blocks: **Face**, **Voice**, **Prompt**, **Knowledge**, **Tools**, and **First Message**. This guide walks you through setting up each one.

<Card title="New to Equos?" href="/quickstart/setup" icon="rocket">
  Create your account and organization before building your first character.
</Card>

***

## Open the character editor

From the [Characters page](https://studio.equos.ai/characters), click the **+** button in the top-right corner—or go directly to [studio.equos.ai/characters/new](https://studio.equos.ai/characters/new).

<Frame>
  <img alt="Character editor in the Equos Studio" />
</Frame>

Give your character a name at the top, then configure each building block on the right-hand panel.

<Note>
  Editing an existing character uses the same flow—just open the character and click the **pen** button in the top-right to enter edit mode.
</Note>

***

## Face

The **Face** is the visual identity of your character.

* Upload a single image—photo, painting, illustration, or AI-generated.
* A clear, front-facing portrait works best; the face should be well-lit and unobstructed.
* Equos handles lip-sync and facial expressions automatically at runtime.

<Tip>
  You only need one image. No multi-angle shoots or training required.
</Tip>

***

## Voice

The **Voice** is how your character sounds.

* Pick a voice from the catalog of built-in options.
* Preview each voice before selecting.
* You can change the voice at any time without affecting anything else.

***

## Prompt

The **Prompt** (also called the **Brain**) defines your character's personality, role, and behavior.

Use it to specify:

* **Identity** — name, background, role (e.g., "You are Tommy, a friendly product coach…")
* **Tone** — formal, casual, playful, empathetic
* **Scope** — what the character should talk about and, just as importantly, what it shouldn't
* **Style** — short replies vs. detailed answers, use of humor, vocabulary level

<Tip>
  Keep prompts concrete. "Answer in 1–2 sentences and always ask a follow-up question" beats "be conversational."
</Tip>

***

## Knowledge

Attach a **Knowledge Base** so your character can ground its answers in your own content (RAG).

* Select an existing knowledge base or create a new one.
* The character will automatically search it during conversations to find relevant passages.
* Great for product docs, FAQs, internal SOPs, or any domain-specific content.

<Card title="Create a knowledge base" href="/recipes/create-knowledge-base" icon="book">
  Learn how to build and populate a knowledge base for your character.
</Card>

***

## Tools

**Tools** let your character take actions during a conversation, not just talk.

Today, tools allow the character to **search the internet** in real time—so it can answer questions about recent events, look up live information, or fetch data it otherwise wouldn't know about.

<Tip>
  Enable tools when your character needs fresh information that isn't in its prompt or knowledge base.
</Tip>

***

## First Message

The **First Message** is the opening line your character speaks the moment a conversation starts.

* Sets the tone immediately
* Introduces the character and what it can help with
* Invites the user to respond

Example: *"Hey, I'm Tommy—your product coach. What are you working on today?"*

***

## Save and chat

Once each block is configured, click **Save** in the top-right. Your character is live.

Head to the character page and click **Start Chatting** to test it end to end.

<Card title="Chat with your character" href="/quickstart/chat-with-character" icon="comments">
  Start a live conversation and try out the mic, camera, and screen-share controls.
</Card>


# Create a Knowledge Base
Source: https://docs.equos.ai/recipes/create-knowledge-base

Give your characters access to your own content so they can answer questions grounded in it.

## What is a knowledge base?

A **knowledge base** is a collection of documents and text that your character can search during a conversation—this is called **RAG** (Retrieval-Augmented Generation).

When a user asks a question, the character looks up the most relevant passages in its knowledge base and uses them to craft a grounded, accurate answer instead of relying solely on what the underlying model "knows."

Typical use cases:

* Product documentation and FAQs
* Internal playbooks and SOPs
* Course material or training content
* Company-specific context (policies, pricing, glossaries)

<Tip>
  Knowledge bases are a great way to keep your character's answers **accurate**, **up to date**, and **on-topic**—without retraining a model.
</Tip>

***

## Prerequisites

<Warning>
  Knowledge bases are a **premium feature**. You'll need to set up billing before you can create one.
</Warning>

Head to the [Billing page](https://studio.equos.ai/billing) and add a payment method first.

***

## Create a knowledge base

<Steps>
  <Step title="Open the Knowledge Bases page">
    Go to [studio.equos.ai/knowledge-bases](https://studio.equos.ai/knowledge-bases).
  </Step>

  <Step title="Create a new knowledge base">
    Click the **+** button, give it a name and a short description, then submit.
  </Step>

  <Step title="Add content">
    Open the knowledge base and add:

    * 📄 **Documents** — upload files (PDF, Markdown, text, etc.)
    * ✍️ **Text** — paste content directly for quick notes, snippets, or instructions

    Each item is automatically chunked, embedded, and indexed so your character can search it.
  </Step>
</Steps>

<Frame>
  <img alt="Knowledge base with indexed documents in the Equos Studio" />
</Frame>

<Note>
  Each knowledge base can hold up to **100 MB** of content. The usage bar on the page shows how much space you've used.
</Note>

***

## Use it with a character

Once your knowledge base is ready, attach it to any character from the **Knowledge** section of the character editor. From then on, the character will automatically search it during conversations.

<Card title="Build your character" icon="sparkles" href="https://studio.equos.ai/characters">
  Head back to your character and plug in your new knowledge base.
</Card>


# Browser
Source: https://docs.equos.ai/sdks/browser

Get started with the Equos Browser SDK to build interactive AI experiences on the Web.

## Installation

Install Equos Browser SDK via npm:

```bash theme={null}
npm i @equos/browser-sdk
```

## Usage

Usage is described in the package documentation.

<Columns>
  <Card icon="npm" title="View package on NPM" href="https://www.npmjs.com/package/@equos/browser-sdk">
    View the package on NPM.
  </Card>

  <Card icon="github" title="View code examples on GitHub" href="https://github.com/EquosAI/equos-examples/blob/main/README.md">
    View code examples on GitHub.
  </Card>
</Columns>


# iOS
Source: https://docs.equos.ai/sdks/ios

Run Equos characters natively on iPhone and iPad with on-device rendering.

<Columns>
  <Frame>
    <img alt="Equos character rendered inside an iOS app" />
  </Frame>

  <div>
    <p>The Equos iOS SDK brings the full character experience to native iOS apps, with <strong>rendering running directly on the device</strong> for real-time performance at any scale.</p>
    <p> </p>
    <p>It runs smoothly on consumer hardware going back to the <strong>iPhone 11</strong>, and can be used either with the full Equos voice pipeline or paired with your own audio stack.</p>
    <p> </p>
    <p><strong>Drop-in simple.</strong> A single component handles video rendering, audio capture, and session lifecycle—no WebRTC wiring, no custom track management, no boilerplate. Your app starts a conversation in a few lines of Swift.</p>
    <p> </p>
    <p><strong>Lowest possible latency.</strong> Because video is rendered directly on the phone, there's no cloud round-trip for every frame. Responses feel instant, even on cellular networks—and entirely network-free when paired with your own on-device audio stack.</p>
  </div>
</Columns>

***

## Two ways to use it

<CardGroup>
  <Card icon="headset" title="Full pipeline">
    Connect to the Equos voice agent and get the full experience: character video, audio, and conversational AI—the same flow as the Web and Next.js integrations.
  </Card>

  <Card icon="video" title="Video rendering only">
    Use the SDK purely for on-device character rendering and plug in **your own voice pipeline**. No network required for video—and no per-minute cost.
  </Card>
</CardGroup>

### Full pipeline

Ideal if you want the fastest path to a complete character experience on mobile.

Unlike the web integration, **you do not create a conversation up front**. Instead:

1. Your backend generates a short-lived **consumer access token** by calling the dedicated Equos API endpoint.
2. Your app passes the token to the iOS SDK.
3. The SDK starts the conversation directly—audio, video, and AI all managed by Equos.

<Note>
  This removes a round-trip: there's no "create conversation, then join" dance. The token alone is enough for the SDK to stand up the live session.
</Note>

### Video-only, bring your own voice

Ideal if you already run your own voice stack (STT/LLM/TTS, or a real-time audio model) and only need a high-quality animated face.

In this mode, **no token, no backend call, no network required**. The iOS SDK renders the character on-device from your audio stream the moment you start it—**no Equos network calls, no per-user cost, unlimited usage**.

This is what makes Equos unique: our rendering model runs in real time on consumer iPhones (including iPhone 11), which means you can ship an animated AI character to millions of users without provisioning a single GPU.

<Card icon="bolt" title="Learn more about on-device rendering" href="/on-device-rendering">
  How Equos scales to millions of users by running on the device itself.
</Card>

***

## Availability

The iOS SDK is currently **private**. We work directly with teams to integrate it into their apps.

<Card title="Request a demo" icon="envelope" href="https://docs.google.com/forms/d/e/1FAIpQLSdoK7LvORdQf7KOQKvhhlESStJcKc3bDB9HPsEet6LuOmVUfQ/viewform">
  Get in touch for a walkthrough, early access, and integration support.
</Card>


# NodeJS
Source: https://docs.equos.ai/sdks/nodejs

Get started with the Equos NodeJS SDK to build interactive AI experiences with ease on NodeJS.

## Installation

Install the Equos NodeJS SDK via npm:

```bash theme={null}
npm i @equos/node-sdk
```

## Usage

Usage is described in the package documentation.

<Columns>
  <Card icon="npm" title="View package on NPM" href="https://www.npmjs.com/package/@equos/node-sdk">
    View the package on NPM.
  </Card>

  <Card icon="github" title="View code examples on GitHub" href="https://github.com/EquosAI/equos-examples/blob/main/README.md">
    View code examples on GitHub.
  </Card>
</Columns>


# Python
Source: https://docs.equos.ai/sdks/python

Get started with the Equos Python SDK to build interactive AI experiences with ease using Python.

## Installation

Install the Equos Python SDK via pip or poetry:

<CodeGroup>
  ```bash pip theme={null}
  pip install equos
  ```

  ```bash poetry theme={null}
  poetry add equos
  ```
</CodeGroup>

## Usage

Usage is described in the package documentation.

<Columns>
  <Card icon="python" title="View package on Pypi" href="https://pypi.org/project/equos/">
    View the package on Pypi.
  </Card>

  <Card icon="github" title="View code examples on GitHub" href="https://github.com/EquosAI/equos-examples/blob/main/README.md">
    View code examples on GitHub.
  </Card>
</Columns>


# React
Source: https://docs.equos.ai/sdks/react

Get started with the Equos React Toolkit to build interactive AI experiences on the Web.

## Installation

Install Equos React SDK via npm:

```bash theme={null}
npm i @equos/react
```

## Usage

Usage is described in the package documentation.

<Columns>
  <Card icon="npm" title="View package on NPM" href="https://www.npmjs.com/package/@equos/react">
    View the package on NPM.
  </Card>

  <Card icon="github" title="View code examples on GitHub" href="https://github.com/EquosAI/equos-examples/blob/main/README.md">
    View code examples on GitHub.
  </Card>
</Columns>