tg-bot-binding

Telegram Bot 連携ガイド

ユーザーが Telegram Bot の連携、セットアップ、接続、確認、または関連するトピックについて質問した場合は、以下のガイドを提供してください。常にユーザーの言語で回答してください。

概要

Starchild では、自分の Telegram Bot を接続して、Telegram 上で AI エージェントと直接チャットできます。Bot を連携する方法は2 つあります。

1. スキャンして Bot を作成（推奨） — QR コードをスキャンし、Telegram で作成を確認すると、Starchild が連携を自動的に完了します。トークンをコピーする必要も、確認コードも不要です。
2. 手動連携 — @BotFather で Bot を作成し、Dashboard にトークンを貼り付けて、コードで所有権を確認します。

可能な限りスキャンして作成する方法を優先してください — より速く、手順も少なくなります。

---

方法 A: スキャンして Bot を作成（推奨）

この方法では、新しい Bot を作成し、ひとつの流れで連携します — トークンも確認コードも不要です。

ステップ 1: Telegram Bot セクションを開く

1. Starchild Dashboard（Web インターフェース）に移動します。
2. ページの左下隅にあるアバターをクリックします。
3. アカウント管理ポップアップで、Telegram Bot セクションを見つけます。
4. **「スキャンして Bot を作成」**をクリックします。

ステップ 2: QR コードをスキャンする

QR コードがリンクとともに表示されます。次のいずれかを行ってください。

• Telegram アプリで QR コードをスキャンする（カメラ → スキャン）、または
• **「Telegram で開く」**をクリックして、作成ページに直接移動します。

ステップ 3: Telegram で作成を確認する

Telegram で Bot 作成ページが開きます。Bot を作成することを確認します。

ステップ 4: 完了！

Starchild が新しい Bot を検出し、連携を自動的に完了します。Bot はそのまま**「running」**になります — 確認コードは不要です。Telegram で /start を送信して、AI エージェントとのチャットを開始してください。

注意: この方法で作成された Bot は、Starchild の Bot インフラストラクチャによって管理されます。後で削除する場合は、Dashboard の Bot を削除アクションを使用してください（@BotFather ではありません）。

---

方法 B: 手動連携（BotFather + トークン）

@BotFather を使用して自分で Bot トークンを作成および所有したい場合は、このフローを使用してください。

ステップ 1: BotFather で Telegram Bot を作成する

1. Telegram を開き、@BotFather（Bot を作成するための公式 Telegram Bot）を検索します。
2. BotFather に /newbot を送信します。
3. プロンプトに従います。
   • Bot の表示名を入力します（例: 「My Starchild Agent」）。
   • Bot のユーザー名を入力します（bot で終わる必要があります。例: my_starchild_bot）。
4. BotFather がBot トークンを返信します — 123456789:ABCdefGHIjklMNOpqrsTUVwxyz のような文字列です。このトークンをコピーして安全に保管してください。 公開しないでください。

ステップ 2: Starchild Dashboard で Bot トークンを追加する

1. Starchild Dashboard（Web インターフェース）に移動します。
2. ページの左下隅にあるアバターをクリックします。
3. アカウント管理ポップアップで、Telegram Bot セクションを見つけます。
4. Bot トークンを貼り付けて送信します。
5. システムが以下を実行します。
   • Telegram の API でトークンを確認します（getMe を呼び出します）。
   • 6 桁の確認コードを生成します（有効期間は 5 分間）。
   • Bot のステータスを**「pending」**に設定します。
6. Dashboard に確認コードが表示されます。このコードをコピーしてください。

ステップ 3: Telegram で Bot の所有権を確認する

確認する方法は 2 つあります。

オプション A: ディープリンク（推奨）

Dashboard に表示されている確認リンクをクリックします。Telegram で Bot が開き、確認コードが自動的に送信されます。リンクの形式は次のとおりです。

https://t.me/<your_bot_username>?start=verify_<CODE>

オプション B: 手動確認

1. Telegram で Bot を開きます（@<your_bot_username> を検索します）。
2. /start を送信します — Bot が確認コードの入力を促します。
3. 6 桁のコードを入力して送信します。

ステップ 4: 完了！

確認が完了すると、Bot のステータスが一時的に**「active」に変わり、その後自動的に「running」**に移行します — つまり、Bot が稼働して準備完了です。Telegram を通じて AI エージェントとのチャットを開始できます。/start を送信して、ウェルカムメッセージと利用可能なコマンドを確認してください。

---

Bot ステータスリファレンス

ステータス	意味
pending	Bot トークンが追加済みで、所有権の確認待ち（手動フローのみ）
active	所有権が確認済みで、実行中へ移行中
running	Bot は稼働中で、すぐに利用可能
deleted	Bot はユーザーによって削除済み

---

トラブルシューティング

「確認コードの有効期限が切れました」

確認コードの有効期限は 5 分 です。期限が切れた場合：

• ダッシュボードに戻り、「コードを更新」 をクリックして新しいコードを生成してください。
• その後、新しいコードを使って Telegram で再度確認を行ってください。

「失敗回数が多すぎます」

5 回 間違った入力を行うと、セキュリティのために確認コードが無効になります：

• ダッシュボードに移動し、Bot を削除 してから 再度追加 して、新しいコードを取得してください。

「Bot トークンはすでに別のユーザーによって登録されています」

各 Bot トークンは 1 つの Starchild アカウントにのみ紐付けられます。このエラーが表示された場合：

• 新しく未使用の Bot トークン を使用していることを確認してください。
• 以前にこのトークンを使用したことがある場合、古い紐付けがまだ残っている可能性があります。@BotFather から新しい Bot を作成してください。

「すでにアクティブな Bot があります」

各アカウントは同時に 1 つのアクティブな Bot のみを持てます：

• Bot を切り替えるには、まずダッシュボードから現在の Bot を 削除 してから、新しい Bot を追加してください。
• 注意：Bot を削除した後、新しい Bot を追加するまでに 1 時間のクールダウン があります。

「クールダウン中 — 新しい Bot を追加する前にお待ちください」

Bot を削除した後、新しい Bot を追加するまでに 1 時間 待つ必要があります。ダッシュボードにクールダウンの終了時刻が表示されます。

「試行回数が多すぎます。しばらく待ってから再試行してください。」

スキャンして作成するフローにはレート制限があります。このメッセージが表示された場合は、しばらく待ってから 「スキャンして Bot を作成」 を再度クリックしてください。

「認証の有効期限が切れました。もう一度お試しください。」

スキャンして作成する QR コード / リンクの有効期限は限られています。期限が切れた場合：

• 現在のペアリングをキャンセルし、「スキャンして Bot を作成」 を再度クリックして新しい QR コードを取得してください。

Bot が Telegram で応答しない

• ダッシュボードで Bot のステータスを確認してください — 「running」 になっている必要があります。
• ステータスが 「pending」 の場合、確認ステップ（手動フロー）を完了してください。
• Bot に /start を送信してみてください。
• 問題が解決しない場合は、Bot を削除して再追加してみてください（1 時間のクールダウン後）。

---

クイックリファレンス

操作	場所
Bot の作成 + 紐付け（最速）	Starchild ダッシュボード → 左下のアバター → アカウント管理 → Telegram Bot → 「スキャンして Bot を作成」 → QR コードをスキャン → Telegram で確認
新しい Telegram Bot を手動で作成	Telegram → @BotFather → /newbot
Bot トークンを追加	Starchild ダッシュボード → 左下のアバター → アカウント管理 → Telegram Bot
所有権を確認	Telegram → あなたの Bot → 確認コードを入力
確認コードを更新	Starchild ダッシュボード → アカウント管理 → Telegram Bot → 「コードを更新」
Bot を削除	Starchild ダッシュボード → アカウント管理 → Telegram Bot → 「Bot を削除」
Bot ステータスを確認	Starchild ダッシュボード → アカウント管理 → Telegram Bot

---

重要な注意事項

• 推奨フロー：「スキャンして Bot を作成」 を使用してください — トークンや確認コードなしで Bot が自動的に作成され、紐付けられます。
• スキャンで作成された Bot は Starchild によって管理されます：これらは Starchild の Bot インフラストラクチャを通じて作成されます。削除する場合は @BotFather からではなく、ダッシュボードから行ってください。
• セキュリティ：手動フローでは、Bot トークンは保存前に暗号化（AES-256）されます。API レスポンスで公開されることはありません。
• 1 アカウントにつき 1 つの Bot：同時に持てるアクティブな Telegram Bot は 1 つだけです。
• クールダウン：Bot を削除した後、新しい Bot を追加するまでに 1 時間待つ必要があります。
• レート制限：Bot の追加とコードの更新は 1 分あたり 3 リクエストに制限されています。
• 確認の試行回数：正しいコードを入力できるのは、無効になるまで 5 回までです。