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

はじめに

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

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

📚 APIドキュメント: https://sdk.metatell.io/bot/

前提条件​

  • Node.js 20以上（推奨: 22+）
  • CLI（@metatell/bot-cli）を使う場合はCLIリファレンスを確認してください。Node.js 22.12以上が必要です。
  • TypeScript（推奨、JavaScriptでも可）
  • metatellルームへのアクセス権限

インストール​

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

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

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

最小実装例​

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

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) {
    // textはSDK側で先頭のメンションを除去済み
    const question = text.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

メソッドとイベントの一覧はAPIリファレンスを参照してください。

環境変数の使用​

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

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

dotenv.config();

const roomId = process.env.METATELL_ROOM_ID?.trim();
if (!roomId) {
  throw new Error('METATELL_ROOM_IDを設定してください');
}

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