Sibrel ボットの開発

最初のボットを作る

• 設定 → ボット → ボットを作成 を開きます。ホストによってはボット作成が無効になっています。
• a-z0-9_ の 2〜32 文字のユーザー名を選びます。トークンは一度しか表示されないので保存してください。
• コミュニティ設定でボットを追加し、必要な権限だけを付与します。管理には MANAGE_BOTS が必要です。
• 自分の端末またはサーバーでボットのプログラムを起動します。ボットのアカウント自体はコードを実行しません。
• トークンを発行したホストの API アドレスを使用します。

ボットは参加しているコミュニティのチャンネルで動作します。ボット API はダイレクトメッセージと公開スペースに対応していません。

認証とシークレット

Authorization: Bearer <BOT_TOKEN>

ボットの操作にはボットトークンが必要です。ボットの作成・編集、コミュニティへの追加、権限の設定には、所有者または管理者のアカウントトークンが必要です。これらは分けて管理してください。

トークンは環境変数に置き、ブラウザーのコードや Git には絶対に書かないでください。ホストのデータベースにはトークンのハッシュだけが保存されます。漏れたトークンは失効させ、再発行してください。ゲートウェイはクエリ文字列でトークンを渡すため、リバースプロキシや監視のログでは URL を伏せてください。HTTPS/WSS を使用してください。

最小の動作例

組み込みの fetch と WebSocket を備えた Node.js 22+ が必要です。ping-bot.en.mjs をダウンロード。この例は /ping を登録し、チャンネルに応答し、切断後に再接続します。

$env:SIBREL_API_URL = "https://api.example.org"
$env:SIBREL_BOT_TOKEN = "your-token"
node ./ping-bot.en.mjs

ボット REST API

POST /api/bots/messages
{
  "channel_id": 42,
  "content": "ボットからの挨拶です！",
  "reply_to_id": 123
}

送信に成功すると 201 { message } を返します。本文がないときは Content-Type: application/json を付けないでください。空の JSON リクエストは 400 になることがあります。

ボットと権限の管理

ボットはコミュニティごとに独自の権限ビットマスクを持ち、通常のメンバーロールとは異なります。チャンネル閲覧：16384、メッセージ送信：32768、音声：65536。この 3 つで 114688 になります。ボットに管理者権限は付与されません。

スラッシュコマンド

PUT /api/bots/commands
{ "commands": [
  { "name": "ping", "description": "Check the bot response", "options": [] },
  { "name": "echo", "description": "Repeat text", "options": [
    { "name": "text", "description": "Your text", "type": "string", "required": true }
  ] }
] }

名前は 1〜32 文字で a-z0-9_-。コマンドは最大 100 個、各コマンドのオプションは最大 10 個。種類は string、number、boolean、user、channel、role、choices は最大 25 個。コマンドの説明は 200 文字まで。

PUT は一覧全体を置き換えるため、常にすべてのコマンドを送ってください。message:create では、認識された呼び出しに command: {bot_id, name, options, args} が含まれます。他のボットのコマンドに応答しないよう bot_id を確認してください。無効または不明なコマンドは通常のテキストとして届きます。

メンバー、チャンネル、ロールの選択

user、channel、role のオプションは手入力ではなく、検索できる一覧から選びます。ボットは名前ではなくメンションのトークンを受け取るため、チャンネル、ロール、メンバーの名前を変更しても送信済みの呼び出しは壊れません。

• 検索は名前のほか、メンバーではニックネームとログイン名にも一致します。
• サービス語も使えます。「voice」で音声チャンネル、「role」でロール、「text」でテキストチャンネルが見つかります。
• 名前の先頭が一致する候補が上位に表示されます。
• 表示されるのは最大 8 件です。目的のものがない場合は検索語を絞ってください。
• Enter で先頭の候補を選択、矢印キーで移動、Esc で検索を消去、Backspace で通常入力に戻ります。

値は command.options（例：{ "user": "<@42>" }）にトークンとして入り、command.args の同じ位置にも現れます。生の ID も受け付けますが、返信テキストでメンションとして表示されるのはトークンだけです。

ゲートウェイとイベント

wss://api.example.org/api/bots/gateway?token=<BOT_TOKEN>

{ "type": "ready", "bot_id": 7, "guilds": [1, 2] }
{ "type": "ping" }
{ "type": "pong" }

イベント：message:create、message:update、message:delete、reaction:add、reaction:remove、interaction。アクションイベントのデータは data にあり、ready は最上位に bot_id と guilds を含みます。

接続ごとのキューは 256 件まで保持します。あふれると message:drop が送られ、古いイベントは失われることがあります。遅延を伴う再接続、pong の監視、REST による状態の復元を実装してください。配信が必ず 1 回だけとは考えないでください。

ボタン、埋め込み、インタラクション

{
  "channel_id": 42,
  "embeds": [{ "title": "テスト", "description": "ボタンを押してください", "color": 5793266 }],
  "components": [{ "type": 1, "components": [
    { "custom_id": "ping", "label": "Ping", "style": 1 }
  ] }]
}

ボタンのラベルは 80 文字まで、custom_id は一意で 100 文字までです。リンクボタンは custom_id の代わりに http/https の URL を使います。最大 5 行、各行 5 個で合計 25 個まで。スタイルは 1〜4（primary、secondary、success、danger）。disabled と emoji に対応します。

{ "type": "interaction-reply", "nonce": "from the event",
  "action": "ephemeral", "content": "Pong！" }

3 秒以内に応答してください。ephemeral はクリックした本人だけに表示され、message はチャンネルに投稿し、update はボタンの付いたメッセージを編集します。一時的な応答はメモリに最大 15 分残り、再起動で消えます。秘密の保管場所ではありません。

content は 2000 文字まで、埋め込みは最大 10 個で合計 6000 文字まで。カスタム絵文字は <:name:id>。埋め込みの例はWebhookもご覧ください。

音声

POST /api/bots/voice/join は channel_id、identity、livekit を返します。LiveKit が設定されていれば、返された token と livekitUrl を互換性のあるクライアント SDK で使ってください。livekit: null の場合、ボットはメンバー一覧に表示されるだけで音声は送信しません。REST リクエスト自体は再生を開始しません。

エラーと運用

ログではシークレットを伏せ、環境変数へのアクセスを制限し、ボット自身のメッセージには応答しないでください。データの収集方法は管理者と利用者で合意し、保持と削除の手順を定めてください。

ボットのボイスチャンネル

個別の CREATE_VOICE_CHANNELS 権限を持つボットは POST /api/bots/guilds/:guildId/channels でボイスチャンネルを作成できます。状態取得：GET /api/bots/guilds/:guildId/voice-states。移動要求：POST /api/bots/guilds/:guildId/voice/move。空チャンネル削除：DELETE /api/bots/channels/:channelId。権限と制限はホストが確認し、トークンだけでは操作権限は得られません。