Skip to content

Developer docs

Connect a Khavee character to your own app with the Platform API and the React SDK, or to a WordPress site with the plugin.

On this pageGet an API key

Get an API key

Each API key belongs to one character (a project in the dashboard). Use it on your server to read the character's settings and manage its knowledge base.

  1. Sign in to the Khavee platform and open API Keys.
  2. Click Create key. Name it (for example Website backend) and pick the character.
  3. Copy the key straight away. It is only shown once.
  4. Store it on your server as an environment variable, for example KHAVEE_API_KEY.

Keep the key on your server. It can read character settings and manage the knowledge base. Never put it in browser code or a public repository. If a key leaks, revoke it under API Keys and create a new one.

Embed on a website

You don't need an API key to put a character on a web page. Publish it, open the Share window and copy the embed code. It loads the character's share page in an iframe.

embed.html
<iframe
  src="YOUR_SHARE_PAGE_URL"
  title="Talk to Khavee"
  width="400" height="640"
  style="max-width: 100%; border: 0;"
  allow="microphone"
></iframe>

Set the share page's access to Anyone with the link so visitors can talk without signing in. Their conversations use your plan's hours.

allow="microphone" lets visitors talk to the character. Use the API key only when your own server needs the character's settings or knowledge base.

Authentication

Send the key in the X-API-Key header. Every endpoint lives under this base URL:

https://api.platform.khavee.ai/api/v1

terminal
curl https://api.platform.khavee.ai/api/v1/projects/sdk/preview \
  -H "X-API-Key: $KHAVEE_API_KEY"

A missing or wrong key returns 401 Unauthorized. The key already identifies its character, so you never pass a project ID.

Endpoints

  • GET/projects/sdk/previewThe character's 3D model, personality and voice settings.
  • GET/projects/sdk/knowledge?limit=50List knowledge facts. Returns 50 by default.
  • POST/projects/sdk/knowledgeAdd a fact. Body: { "content": "...", "metadata": { } }
  • DELETE/projects/sdk/knowledge/{id}Remove a fact by its numeric ID.
  • GET/projects/sdk/knowledge/search?query=...&topK=5Find the facts closest to a question. Returns 5 by default.

SDK client

KhaveeClient in @khaveeai/core adds the header for you. Run it on your server. getProjectPreview() covers the character; for the knowledge endpoints use the client's get, post and delete methods.

terminal
npm install @khaveeai/core
server.ts
import { KhaveeClient } from '@khaveeai/core'

const khavee = new KhaveeClient({ apiKey: process.env.KHAVEE_API_KEY })
const project = await khavee.getProjectPreview()
const facts = await khavee.get('/projects/sdk/knowledge?limit=50')

Render the avatar

@khaveeai/react draws the character with three.js. It lip-syncs, blinks and plays talking animations on its own while the AI speaks. Use VRMAvatar for .vrm files and GLBAvatar for .glb files.

terminal
npm install @khaveeai/react three @react-three/fiber @react-three/drei
Reception.tsx
<KhaveeProvider config={{ realtime: provider }}>
  <Canvas camera={{ position: [0, 1.5, 3] }}>
    <VRMAvatar src="/models/your-avatar.vrm" />
  </Canvas>
</KhaveeProvider>

Voice providers

The provider decides how speech gets in and out. All three plug into the same components, so you can switch later without touching your UI.

  • OpenAIRealtimeProvider

    Full-duplex voice over WebRTC. Lowest latency, and the customer can interrupt.

  • OpenAISTTTTSProvider

    Turn-based: speech to text, chat, then text to speech.

  • GenericPipelineProvider

    Compose your own pipeline from any VAD, STT, LLM and TTS vendors, including non-OpenAI services.

Point the provider at your own backend route (proxyEndpoint) so the OpenAI key stays on the server.

Tool calling

Tools are plain JavaScript objects. The AI calls them when the conversation needs one, for example to book a slot.

tools.ts
provider.registerFunction({
  name: 'book_appointment',
  description: 'Book a consultation slot',
  parameters: { time: { type: 'string', required: true } },
  execute: async ({ time }) => ({ success: true, message: `Booked for ${time}` }),
})

WordPress plugin

Put a talking character on any WordPress page without writing code. Requires WordPress 6.0 or newer and PHP 8.0 or newer.

Install

Download the latest release zip from github.com/khavee-ai/khavee-wp-plugin, then go to Plugins, Add New, Upload Plugin. New releases arrive through the plugin's built-in update checker.

Settings

Open Khavee AI Avatar in the WordPress admin menu.

OpenAI API Key
Powers the voice. Saved on the server and shown masked.
Khavee Platform API Key
The key from API Keys in the dashboard. Lets the character answer from the knowledge base you manage on the platform.
Personality / Instructions
How the character talks and what it should do.
Voice
Pick one of the supported voices.
Avatar (VRM/GLB)
Upload a .vrm or .glb file through the Media Library.
Floating widget
Show the character in a corner on every page. Set its colours, position, size and camera angle.

Shortcode and block

Place the character inside a page with the shortcode. Each attribute overrides the setting for that page only; avatar takes a Media Library attachment ID.

shortcode
[khaveeai_avatar]
[khaveeai_avatar voice="shimmer" instructions="Answer in Thai." avatar="123"]

In the block editor, search for Khavee AI Avatar. The block uses the same settings as the shortcode.