アクション(動作ノード)リファレンス

「アクション(動作)」は、Bot が実際に行う処理を表すノードです。メッセージの送信や編集、チャンネル・ロールの操作、サーバー管理(Ban や Kick など)、外部サービスとの連携まで、Bot にさせたいことのほとんどはこの動作ノードで組み立てます。

アクションノードとは

アクションノードは、前のノードから線(エッジ)でつなぐことで「この処理の次にこの処理を行う」という順番を作ります。

アクションノードの使い方

サイドバーの「動作」グループから使いたいアクションをキャンバスに置き、前のノードから線をつないで、ノードの設定パネルでそのアクション固有の項目を入力します(ノードの追加・接続・編集の基本操作は コマンドビルダーの概要と使い方 を参照してください)。メッセージにボタンや選択メニューを付けたい場合は「メッセージを送信」の設定パネルから追加し、Ban や Kick などの管理操作では対象となるユーザーをオプションや変数で指定します。

ほとんどの入力欄では、固定の文字や ID のかわりに変数を使えます。入力欄の横に変数ボタンがある項目では、コマンドのオプションや前のノードで作った変数(例: {option_user} や {msg_1})を差し込めます。変数の書き方は 変数と式の使い方 を参照してください。

すべてのノードに共通する「ノードタイトル」

ほぼすべての動作ノードの設定パネルの最後にある「ノードタイトル」は、キャンバス上での表示名を変えるだけの項目で、コマンドの動作には影響しません。

---

メッセージ応答

ユーザーや指定したチャンネルに向けて、Bot からメッセージを送り出すノードです。

メッセージを送信

テキストや埋め込み(Embed)を送信でき、ボタンや選択メニューを付けることもできます。送信したメッセージの ID を変数に保存して、あとから編集・削除・ピン留めの対象にもできます。

送信先と表示の設定

送信先で「コマンド実行者のDM」を選ぶと、DM は常にコマンドを実行した本人へ送られます。送信先のユーザーを ID や変数で指定して任意のユーザーへ DM を送る機能(任意ユーザー宛て DM 送信)は未実装です。

メッセージ形式を選ぶ

メッセージの作り方を 2 形式から選べます(既定は「通常 (本文 + Embed)」)。

本文や Embed を入力した状態で「Components V2 (高度なレイアウト)」へ切り替えようとすると確認を求められ、キャンセルすれば「通常 (本文 + Embed)」のまま据え置かれます。切り替えても本文・Embed の設定自体はエディタ上に保持されるため、「通常 (本文 + Embed)」に戻せば再び使えます。

Components V2 の詳しい組み立て方は Components V2(高度なレイアウト) を参照してください。

本文・埋め込み・コンポーネントのいずれも空のまま「メッセージを送信」を実行すると、Bot は何も送信せずに次の処理へ進みます(エラーにはなりません)。送信先が「コマンド実行と同じチャンネル」のときはコマンドの応答として、特定チャンネルや DM のときは Bot の通常メッセージとして表示されます。

メッセージ内容(本文と埋め込み)を編集する

以下の「メッセージビルダー」は、メッセージ形式が「通常 (本文 + Embed)」のときに表示されます。「メッセージ内容」の項目にある「メッセージビルダー」ボタンから、専用の編集画面(モーダル)を開きます。ここで本文と埋め込み(Embed)を作成し、プレビューで Discord 上での見た目を確認しながら編集できます。

• メッセージ本文: 通常のテキストを入力します(最大 2000 文字)。Discord のマークダウン記法が使えます。
• 埋め込み(Embed): 「Embed追加」ボタンで枠付きのリッチなメッセージを追加できます。1 つの埋め込みには著者(Author)・タイトル・説明文・カラー・画像 URL・サムネイル URL・フッター・タイムスタンプ表示などを設定できます。設定は「基本設定」「著者 (Author)」「画像設定」「フッター」「フィールド」のタブに分かれています。
• フィールド(Field): 各埋め込みの「フィールド」タブにある「フィールドを追加」ボタンで項目を追加できます。名前(Name)と値(Value)を入力し、「Inline」をオンにすると横並びになります。フィールドは 1 つの埋め込みにつき最大 25 個です。

埋め込み(Embed)は 1 つのメッセージに最大 10 個まで追加できます。

ボタンや選択メニューを追加する

「コンポーネントの追加」セクションは、メッセージ形式が「通常 (本文 + Embed)」のときに表示されます。ここで、メッセージにインタラクション部品を付けられます。

• 「ボタンを追加」をクリックすると、ボタンのノードが子として追加・接続されます。
• 「選択メニューを追加」をクリックすると、選択メニュー(ドロップダウン)のノードが追加・接続されます。

追加されたボタン・選択メニューのノードをクリックすると、それぞれの設定パネルが開きます(設定内容は後述の「ボタンの設定」「選択メニューの設定」を参照)。

さらに「インタラクションモード」で、ボタンやメニューがクリックされたあとの挙動を選べます。

ボタン/セレクトの永続化を設定する

ボタンや選択メニューの寿命を決める「ボタン/セレクトの永続化」は、インタラクションモード(分岐/フォーム)とは独立して設定できます。

「永続」で送ると、ボタンや選択メニューが Bot を再起動したあとでも反応し続けるようになります。これにより、ロールパネル(押すとロールが付くボタン)や常設の応募パネルのような「ずっと貼っておくボタン」を、カスタムコマンドで自分で作れます(/ticket や /reminder などの常設パネルと同じ仕組みです)。一度きりの確認や、その場限りの操作には「一時的」が向いています。

「永続」から「一時的」に戻すと、「操作できるユーザー」「セッション有効期限(秒)」の設定は自動的にクリアされます。

永続の選択メニューは「自分で選択肢を定義する文字列セレクト」のみ対応で、ユーザー/ロール/チャンネルの選択メニューは永続に対応していません。

ボタンの設定

「ボタンを追加」で作られたボタンノードの設定です。

親の「メッセージを送信」がフォームモードのときは、追加で「フォーム動作」を選べます。「確定 (Submit)」は選択メニューの選択値を確定して次のフローへ進め、「キャンセル (Cancel)」はフォームを破棄します。

選択メニューの設定

「選択メニューを追加」で作られた選択メニュー(ドロップダウン)ノードの設定です。

モーダルを送信

実行者に**ポップアップの入力フォーム(モーダル)**を表示し、入力された値を変数として後続のノードで使えるようにします。スラッシュコマンドのオプション(引数)だけでは足りない複数項目の入力(応募フォーム、設定ウィザードなど)を、ひとつのフォームでまとめて受け取れます。

モーダルの起動経路

モーダル(入力フォーム)は、フローの中での「モーダルを送信」の置き場所によって、次の 2 通りで表示されます。

• エントリ起動: コマンドの最初のアクションが「モーダルを送信」のとき、コマンドを実行した瞬間に最初の応答としてモーダルが表示されます。たとえばスラッシュコマンドを実行すると、すぐに入力フォームがポップアップで開きます。
• ボタン起動: フローの途中でも、ボタンの出力から「モーダルを送信」へ線をつなぐと、そのボタンをクリックしたタイミングでモーダルが開きます。先にメッセージやボタンを送ってから、ボタン操作に応じてフォームを出す、といった流れを作れます。

どちらの場合も、入力フィールドに設定した変数に値が入り、モーダル送信後の後続ノードからその値を参照できます。

モーダルビルダーで入力フィールドを作る

「モーダルビルダー」ボタンから開く編集画面では、「プレビュー」で Discord 上での見た目を確認しながらフォームを組み立てられます。

• 基本設定: 「モーダルタイトル」(最大 45 文字)を入力します。フォーム上部に表示される見出しです。
• フィールド: 「フィールドを追加」ボタンで入力欄を追加します(最大 5 個)。各フィールドには「ラベル」「説明 (任意)」「必須」(「はい」/「いいえ」)、後続ノードで参照する「変数名」を設定します。
• 変数: 追加した各フィールドの変数名と、その値が「文字列」で返るか「配列」で返るか(複数選択のフィールドは配列)を一覧で確認できます。

各フィールドは「フィールド種別」で次のいずれかを選べます。

選択メニュー・ユーザー/ロール/メンション/チャンネル選択では「複数選択」を「複数選択」にすると複数の項目を選べ、「最小選択数 (任意)」「最大選択数 (任意)」も指定できます。ラジオボタンは単一選択のみです。

ラベルやプレースホルダー・デフォルト値には変数を差し込めます。各フィールドに設定した変数名は、後続ノードで波かっこで囲んで参照します(複数選択のフィールドは配列として返ります)。

---

メッセージ操作

すでに送信されたメッセージに対して、ピン留め・リアクション・編集・削除などを行うノードです。多くは「メッセージ変数」(「メッセージを送信」で保存した変数)または「メッセージID」で対象を指定します。

メッセージのピン留め

指定したメッセージをチャンネルにピン留めします(パレットでは「メッセージをピン止めする」)。

リアクションを追加

指定したメッセージに絵文字リアクションを付けます(パレットでは「メッセージにリアクションする」)。

メッセージの編集

Bot が過去に送信したメッセージの本文や埋め込みを編集します(パレットでは「メッセージを編集」)。編集後の本文と埋め込みは「新しいメッセージ内容」の「メッセージビルダー」ボタンから設定します(「メッセージを送信」と同じビルダーです)。

メッセージの削除

指定したメッセージを削除します(パレットでは「メッセージを削除」)。

メッセージ一括削除

チャンネル内のメッセージをまとめて削除します(パレットでは「メッセージの消去」)。

実行時の挙動:

• 削除できる件数は 1 回につき 100 件までです。100 を超える値を入れても自動的に 100 件に丸められます。
• コマンドの応答メッセージなど、実行中に投稿された新しいメッセージは削除対象から自動的に除外されます。コマンド自身の応答を巻き込んで消してしまうことはありません。
• 投稿から 14 日以内のメッセージは Discord の一括削除でまとめて高速に消されます。14 日より古いメッセージは 1 件ずつ削除されるため、処理に時間がかかります。
• テキストチャンネルとスレッドでのみ動作します(ボイスチャンネルやカテゴリーでは動作しません)。

---

チャンネル操作

サーバーのチャンネルを作成・編集・削除するノードです。

チャンネル作成

新しいチャンネルを作成します(パレットでは「チャンネルを作成」)。作成したチャンネルの ID を変数に保存できます。

権限を 1 件追加するごとに、対象の「ID」と「タイプ」(「ロール」/「メンバー」)、許可・拒否する権限を選びます。不要になった権限は「権限を削除」で外せます。

チャンネル編集

既存のチャンネルの設定を変更します(パレットでは「チャンネルを編集」)。

チャンネル削除

指定したチャンネルを削除します(パレットでは「チャンネルを削除」)。

削除されたチャンネルは復元できません。ボイスチャンネルを削除すると、接続中のユーザーは切断されます。この操作には Bot に Manage Channels 権限が必要です。

---

ロール操作

メンバーへのロールの付与・はく奪、ロールの作成・編集・削除を行うノードです。

ロール追加(付与)

指定したユーザーにロールを付与します(パレットでは「ロール付与」)。

ロール削除(はく奪)

指定したユーザーからロールを取り除きます(パレットでは「ロールはく奪」)。

ロール作成

新しいロールを作成します(パレットでは「ロール作成」)。作成したロールの ID を変数に保存できます。

ロール編集

既存のロールの設定を変更します(パレットでは「ロール編集」)。

ロール削除

「削除するロールID」で指定したロールを削除します(パレットでは「ロール削除」)。削除されたロールは元に戻せず、そのロールが付与されていたメンバーからは一斉に外れます。

---

サーバー操作

メンバーへのモデレーション(Ban・Kick・Timeout)やニックネーム変更、招待リンクの作成を行うノードです。

メンバーのBAN

指定したユーザーをサーバーから Ban します(パレットでは「メンバーのBAN」)。

削除するメッセージの期間は 0〜7 日の範囲です。範囲外の値を入れても自動的にこの範囲に丸められます。Ban されたユーザーはサーバーから退出させられ、Ban を解除しない限り再参加できません。すでに Ban 済みのユーザーに対して再度実行しても変化はなく、エラーにもなりません。

メンバーのKick

指定したユーザーをサーバーから追放します(パレットでは「メンバーのKick」)。Ban と異なり、再参加自体は防げません。

メンバーのTimeout

指定したユーザーを一時的にタイムアウト(発言・反応を一定時間できない状態)にします(パレットでは「メンバーのTimeout」)。

タイムアウト中のメンバーは、チャンネルを閲覧できますが、メッセージの送信・リアクション・ボイスの利用ができなくなります。期間は Discord の上限である 28 日までです。28 日を超える期間を指定した場合は 28 日に丸められます。すでにより長いタイムアウトが設定されているメンバーに、より短いタイムアウトを設定しても変化はなく、エラーにもなりません。

メンバーのニックネーム編集

指定したユーザーのサーバー内ニックネームを変更します(パレットでは「メンバーのニックネーム編集」)。

ニックネームは Discord の上限である 32 文字までです。32 文字を超える文字列を指定すると Discord 側で拒否され、コマンドはエラーになります。

インスタント招待の作成

サーバーへの招待リンクを作成します(パレットでは「インスタント招待の作成」)。

有効期限は最長 7 日までです。7 日を超える日数を指定しても 7 日に丸められます。作成した招待リンクは指定した変数(既定では invite_link)に URL として保存され、後続の「メッセージを送信」でそのまま差し込めます。カテゴリーチャンネルには招待リンクを作成できません。

---

API操作

外部サービスと連携するためのノードです。

APIリクエストを行う

外部の API に HTTP リクエストを送り、そのレスポンスを変数に保存して、後続のノードで使うためのアクションです。コマンドビルダー側に「API リクエストビルダー」が組み込まれており、URL・メソッド・クエリ・ヘッダー・認証・ボディ・Cookie・詳細設定をひとつのウィンドウで編集できます。リクエストを実機で試す「テスター」もあり、保存前に挙動を確かめられます。リクエストビルダーは ベータ版 で、仕様や入力欄は今後の改善で変わることがあります。

設定パネル(ノード側)

「APIリクエスト名」はレスポンスを受け取る変数の名前で、必須項目です。入力すると「リクエストビルダーを開く」ボタンが押せるようになります。

「APIリクエスト名」を入力すると、設定パネルに レスポンス変数 が表示されます(APIリクエスト名 が myApi の場合の例)。

リクエストビルダーの構成

メソッドとエンドポイント URL を入力し、次のタブを切り替えながら細部を設定します。

メソッドと URL

メソッドは GET / POST / PUT / PATCH / DELETE から選べます。POST / PUT / PATCH / DELETE 以外を選んでいるときは、ボディ形式が自動で「なし」に固定されます。

エンドポイント URL の欄では https://api.example.com/v1/resource のような完全な URL を入力します。{変数} の埋め込みも使えます。

認証(Bearer / Basic / API Key)

認証タブの「認証方式」を選ぶと、それぞれに対応した入力欄が表示されます。設定した内容はリクエスト送信時に 適切なヘッダー/クエリへ自動で組み込まれ、ヘッダータブの上段に「自動付与されるヘッダー (認証 / Cookie / ボディ形式から生成、編集不可)」として確認できます。

トークンなど秘密にしたい値は、環境変数 の シークレット として登録し、{env.NAME} の形で参照してください。ダッシュボード上でも値が表示されず、Bot 側で送信時にだけ展開されます。

ボディ形式

「ボディ」タブで形式を切り替えると、入力エリアもそれに応じて切り替わります。

「Content-Type」が自動付与される形式を選んだときは、ヘッダータブの「自動付与されるヘッダー」にその値が現れます。手動で同じ名前のヘッダーを足す必要はありません。

詳細設定(タイムアウト・リトライ・失敗時の挙動など)

「詳細設定」タブには、リクエストの挙動を調整するための設定が並びます。

Cookie タブ

Cookie タブでは name=value の組を 1 件ずつ並べます。保存・送信時に Cookie ヘッダーへ集約されます(例: session_id=abc; user=foo)。

テスター

テスターでは設定内容そのままでリクエストを送り、レスポンスの本文・ステータス・ヘッダーを確認できます。

シークレットの環境変数 ({env.X}) を含むリクエストでは、本物の値を画面に出さないよう、テスター内に注意書きが表示されることがあります。レスポンスをそのまま {APIリクエスト名.response} 経由でメッセージに流すと、エコーバック型 API の場合に秘密情報が Discord に漏れる可能性があるため、ノード設定画面側でも警告が出ます。

保存と閉じる

「閉じる」ボタンを押すと、設定内容が そのまま保存 され、ウィンドウが閉じます。URL が空・形式不正・許可されていない宛先のときは保存できず、ウィンドウは閉じません。値を直してからもう一度閉じてください。

IFTTTトリガーを実行する

IFTTT の Webhooks サービスを通じて、指定したイベントで IFTTT のアプレットをトリガーします。

このノードは現在開発中です。 設定の保存はできますが、現時点では Bot 側で実行されません。

利用するには、設定パネルの「IFTTTアカウントと連携」ボタンから、あらかじめ IFTTT アカウントと BotShade アカウントを連携しておく必要があります。

---

変数操作について

変数を作る・計算する・消す操作(変数の設定、変数への演算の適用、変数の削除)も動作ノードの一種ですが、変数の仕組みや式の書き方とあわせて理解したほうが分かりやすいため、別ページにまとめています。詳しくは 変数と式の使い方 を参照してください。

• **永続変数(BSVAR_ で始まる変数)**は、コマンドの実行をまたいで値が保存されます。サーバー単位・ユーザー単位・サーバー内のユーザー単位のいずれかの範囲で保持され、次回以降のコマンド実行でも値が引き継がれます。これらは事前にダッシュボードの「Storage(保管)」から登録しておく必要があり、登録していない BSVAR_ 変数に値を入れようとしても、その代入は無視され値は変わりません(エラーにはなりません)。
• **一時変数(BSVAR_ で始まらない変数)**は、そのコマンドの 1 回の実行中だけ有効で、実行が終わると消えます。
• 「変数の削除」で値を消せるのは永続変数(BSVAR_)だけで、消去すると登録時に決めた既定値に戻ります。一時変数に対して実行しても何も起きません。
• 「変数への演算の適用」では、永続変数(BSVAR_)に対しては安全な更新が行われます。同じ変数を複数のコマンドが同時に書き換えても、一方の更新が消えてしまう(更新の取りこぼし)ことがないよう、内部で順番に処理されます。

---

実際の動作と既定値

各アクションを実行したときの効果と、設定を省略したときに使われる既定値をまとめます。

何も指定しないときに使われる既定値

「すでにその状態」のときの挙動(何もしない)

次の操作は、対象がすでに目的の状態になっている場合、何も変更せずにそのまま次の処理へ進みます。エラーにはなりません。

• すでに持っているロールの「ロール追加」、持っていないロールの「ロール削除」、Ban / Kick 済みまたは退出済みのユーザーへの同じ操作、削除済みのメッセージ・チャンネル・ロールの再削除、ピン留め済みメッセージの再ピン留め。
• 「メッセージの編集」で本文も埋め込みも空のまま実行した場合(誤ってメッセージを空にしてしまわないよう、何も変更しません)。

ID の保存と引き継ぎ

• 「メッセージを送信」で変数名を指定すると、送信したメッセージの ID がその変数に保存され、後続の「メッセージの編集」「リアクションを追加」「メッセージのピン留め」「メッセージの削除」で対象として使えます。
• 「チャンネル作成」「ロール作成」は、作成したチャンネル・ロールの ID を変数に保存します。これを使って「チャンネル編集/削除」「ロール追加/削除/編集/削除」につなげられます。
• ロール ID やチャンネル ID の欄には、メンション(<@&...> や <#...>)・ID・変数・サーバー内の名前のいずれでも指定できます。名前で指定した場合、同じ名前のロールやチャンネルが複数あると、最初に見つかったものが使われます。

---

上限と丸め込み

各アクションには Discord 由来の上限があります。上限を超える値を入力した場合、多くは自動的に上限値へ丸められ、コマンドは止まりません(ニックネームのみ Discord 側で拒否されエラーになります)。

「待機」の上限が 25 秒なのは、コマンド全体の実行時間に約 30 秒の上限があるためです。待機中はユーザーには何も表示されず、待機が終わってから次のアクションが実行されます。

---

表示されるメッセージ

アクションの実行中に、Bot がユーザーに見せる文言は限られています。多くの「すでにその状態」「対象が見つからない」といったケースは、エラーを出さずに静かにスキップされます。

• 操作の途中で Bot に必要な権限がなかった場合(例:Ban Members 権限がないのに BAN を実行)など、処理が失敗したときは、共通のエラー文 An error occurred while executing the command. が表示されます。具体的な失敗理由はサーバー側の記録に残りますが、ユーザーには出ません。
• ロール・チャンネル・サーバー管理などの操作は、Discord の監査ログに記録されます。コマンドビルダー経由の操作には CmdBuilder: /コマンド名 のような理由が付与されるため、あとから「どのコマンドが何をしたか」を管理者が確認できます。

---

注意点・うまくいかないとき

• 権限が足りないと失敗します。 各アクションには対応する Bot 権限が必要です(メッセージ操作は Manage Messages、ロール操作は Manage Roles、BAN は Ban Members、Kick は Kick Members、Timeout は Moderate Members、チャンネル操作は Manage Channels、招待は Create Invite など)。権限がないと、共通のエラー文が表示されて処理が止まります。
• ロールの上下関係に注意してください。 Bot は、自分の最上位ロールより上にあるロールを付与・削除・編集できません。また、自分より上の立場のメンバーに対するロール操作やモデレーションもできず、失敗します。「ロール作成」で作られるロールは、Bot の最上位ロールのすぐ下に配置されます。
• 実行中のチャンネルを削除しないでください。 「チャンネル削除」でコマンドを実行しているそのチャンネルを削除すると、それ以降のメッセージ送信が失敗します。チャンネルを削除する処理は、後続でメッセージを送る処理の前に置かないようにしてください。
• ニュースチャンネルの作成にはコミュニティサーバーが必要です。 コミュニティ機能が有効でないサーバーでニュースチャンネルを作成しようとすると失敗します。
• ボイスチャンネルにはトピックや NSFW を設定できません。 チャンネルタイプに合わない項目は反映されません。
• カスタム絵文字が見つからないとリアクションは付きません。 「リアクションを追加」でカスタム絵文字を指定しても、その絵文字が Bot から参照できない場合、リアクションは付かずにスキップされます(エラーにはなりません)。形式は emoji_name:123456789012345678 です。
• 編集できるのは Bot 自身のメッセージだけです。 他のユーザーが送ったメッセージは「メッセージの編集」では変更できません。
• 「中断」「次の繰り返しへ」は繰り返しの中だけで使えます。 これらは繰り返し(ループ)の内部に置く必要があり、繰り返しの外に置くとエラーになります(ビルダー側でも配置を防いでいます)。「中断」で抜けるときはループの後処理が 1 回実行され、「次の繰り返しへ」では後処理は実行されません。
• DM ではサーバー操作はできません。 チャンネル作成やロール操作など、サーバーが前提のアクションは、DM での実行時には何もせずスキップされます。

---

アクション一覧

変数操作・制御フローを含む全ノードのパレット表記と役割の一覧は ノードの種類リファレンス にまとめています。

アクションの利用にプレミアム加入は必要ありません(現在はベータ版のため、全ユーザーにプレミアムが付与されています。詳しくは プレミアムプラン を参照してください)。

---

次のステップ / 関連ページ

• コマンドビルダーの概要と使い方 — キャンバスとノードの基本操作
• オプション — コマンドに入力欄(引数)を追加する
• 条件分岐 — 状況に応じてフローを分ける
• 制御フロー — 待機・繰り返し・分岐合流など
• 変数と式の使い方 — 変数の参照と計算
• ノードの種類リファレンス — 全ノードの一覧