メインコンテンツまでスキップ

はじめに

metatell Bot SDKを使用して、metatellルームで動作するAIボットを開発するためのガイドです。チャットボット、音声応答ボット、アバター制御など、様々な機能を実装できます。

📦 GitHubリポジトリ: https://github.com/urth-inc/metatell-ai-bot

📚 APIドキュメント: https://urth-inc.github.io/metatell-ai-bot

前提条件​

  • Node.js 20以上（推奨: 22+）
  • TypeScript（推奨、JavaScriptでも可）
  • metatellルームへのアクセス権限

インストール​

# npmを使用
npm install @metatell/bot-sdk

# yarnを使用
yarn add @metatell/bot-sdk

# pnpmを使用
pnpm add @metatell/bot-sdk

最小実装例​

基本的なチャットボットを実装する最小コードです：

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

// クライアントの作成
const client = createMetatellClient({
  serverUrl: 'wss://metatell.app',
  roomId: 'YOUR_ROOM_ID',  // ルームIDを指定
  username: 'MyBot',       // ボットの表示名
  debug: true              // デバッグログを有効化
});

// 接続
await client.connect();

// ボット情報を保存
const botInfo = await client.getInfo();
console.log('Bot connected:', botInfo.name);

// メッセージハンドリング（メンション時のみ応答）
client.chat.onMessage(async ({ from, text, mention, reply }) => {
  // 自分へのメンションをチェック
  // メンション形式: [@DisplayName](session-id)
  if (mention?.sessionId === botInfo.sessionId) {
    // メンションを除いたテキストを取得
    const question = text.replace(/\[@[^\]]+\]\([^)]+\)\s*/, '').trim();

    // 簡単な応答を返す
    await reply(`こんにちは ${from.name}さん！「${question}」についてお答えします。`);
  }
});

// 接続維持
process.on('SIGINT', async () => {
  await client.disconnect();
  process.exit(0);
});

主要な機能​

チャット機能​

// メッセージ送信
await client.chat.send('Hello, everyone!');

// 特定ユーザーへメンション
// 形式: [@DisplayName](session-id)
await client.chat.send('[@Username](session-id) こんにちは！');

// 注意: メッセージ履歴取得APIは現在提供されていません

アバター制御​

// アバター選択
await client.avatar.select('avatar-id');

// 移動
await client.avatar.moveTo({ x: 10, y: 1.6, z: -5 });

// アニメーション再生
await client.avatar.play({
  id: 'wave',
  loop: false,
  duration: 2  // 秒指定
});

// 回転
await client.avatar.rotateTo({ x: 0, y: 90, z: 0 });

イベントハンドリング​

// ユーザー入室
client.on('user-join', (user) => {
  console.log(`${user.name} joined the room`);
});

// ユーザー退室
client.on('user-leave', (user) => {
  console.log(`${user.name} left the room`);
});

// 接続状態の監視
client.on('connected', () => {
  console.log('Bot connected');
});
client.on('disconnected', () => {
  console.log('Bot disconnected');
});

設定オプション​

createMetatellClientで使用できる主要なオプション：

オプション説明デフォルト
serverUrlmetatellサーバーのURL必須
roomId接続するルームID必須
usernameボットの表示名MetatellBot
avatarId使用するアバターIDランダム
debugデバッグログの有効化false

環境変数の使用​

セキュリティのため、認証情報は環境変数で管理することを推奨：

# .env
METATELL_ROOM_ID=abc1234
METATELL_BOT_USERNAME=MyBot
import { createMetatellClient } from '@metatell/bot-sdk';
import dotenv from 'dotenv';

dotenv.config();

const client = createMetatellClient({
  serverUrl: 'wss://metatell.app',  // serverUrlは必須
  roomId: process.env.METATELL_ROOM_ID,
  username: process.env.METATELL_BOT_USERNAME,
});
に最終更新