Getting Started

This guide creates a bot that connects to a metatell room and replies when it is mentioned in chat.

Prerequisites

• Node.js 20 or later. Node.js 24 is recommended and is the version used in CI.
• A metatell room URL.
• An access token if the bot needs room-role permissions, such as text chat in rooms that restrict it.

Install

npm install @metatell/bot-sdk
Copy

For voice bots, install the realtime package as well:

npm install @metatell/bot-sdk @metatell/bot-realtime
Copy

Create a Bot

import { createMetatellClient } from '@metatell/bot-sdk'

const client = createMetatellClient({
  serverUrl: 'wss://metatell.app',
  roomId: 'YOUR_ROOM_ID',
  username: 'GuideBot',
  authToken: process.env.METATELL_TOKEN,
})

await client.connect()
const botInfo = await client.getInfo()

client.chat.onMessage(async ({ from, text, mention, reply }) => {
  if (mention?.sessionId !== botInfo.sessionId) return

  await reply(`Hello ${from.name ?? 'there'}. You said: ${text}`)
})
Copy

Configuration

Option	Required	Description
serverUrl	Yes	WebSocket origin for your metatell environment, for example wss://metatell.app.
roomId	Yes	Room identifier from the metatell room URL.
authToken	No	OIDC access token sent when joining the room. It gives the bot room-role permissions. Store it in an environment variable.
username	No	Display name for the bot avatar. Defaults to MetatellBot.
avatarId	No	Avatar ID to spawn. When omitted, the first organization avatar is used.
avatarSrc	No	GLTF URL used when avatarId is an organization avatar UUID.
defaultAvatarId	No	Fallback avatar ID when no avatarId or organization avatar is available.
debug	No	Enables verbose SDK logs.

Parse a Room URL

If your application receives a full room URL, derive serverUrl and roomId before creating the client:

const roomUrlValue = process.env.METATELL_ROOM_URL
if (!roomUrlValue) {
  throw new Error('METATELL_ROOM_URL is required')
}

const roomUrl = new URL(roomUrlValue)
const serverUrl = `wss://${roomUrl.host}`
const roomId = roomUrl.pathname.split('/').filter(Boolean)[0]

if (!roomId) {
  throw new Error('Room ID was not found in METATELL_ROOM_URL')
}
Copy

Run the Basic Example

cd examples/basic-bot
npm install
npm run build
npm start -- https://metatell.app/YOUR_ROOM_ID
Copy

Add --debug after the room URL to print verbose logs:

npm start -- https://metatell.app/YOUR_ROOM_ID --debug
Copy

Next Steps

• Use API overview for available chat, room, avatar, voice, and event APIs.
• Use Examples for command handling, following users, voice streaming, Dify integration, and behavior trees.
• Use Troubleshooting if connection, authentication, or voice setup fails.