Telegram カスタマー サービス システム構築のための一般的なトラブルシューティング ガイド: トークン、Webhook、エージェントのログインと転送の失敗

安定した テレグラム カスタマー サービス システムを構築することは、多くの国境を越えたチーム、Web3 プロジェクト関係者、コミュニティ オペレーターにとって緊急の必要性です。しかし、実際の導入プロセスでは、Bot Token の失敗から Webhook の競合、エージェントのログイン不能、セッション オフロードの機能不全など、さまざまな種類の障害が次々と発生しました。この記事では、TG-Staff をメイン シナリオとして使用し、Telegram カスタマー サービス システムを構築する際に発生する最も一般的な 6 種類の障害を要約し、実践的なトラブルシューティング方法を提供します。試用版にサインアップしたばかりの場合でも、既に運用を開始している場合でも、このトラブルシューティング ガイドは、問題を迅速に特定し、カスタマー サービスの運用を復元するのに役立ちます。

障害 1: ボット トークンが無効か期限切れです

ボット トークンは Telegram Bot の一意の ID 認証情報であり、顧客サービス システムと Telegram サーバー間の「パスワード」に相当します。トークンの有効期限が切れると、カスタマー サービス システム全体がメッセージを送受信できなくなります。

トークンが有効かどうかを判断するにはどうすればよいですか?

最も簡単な方法は、Telegram Bot API を介してテストすることです。端末またはブラウザで次のリクエストを実行します。

https://api.telegram.org/bot<你的Token>/getMe

{"ok":true,"result":{"id":...}} が返された場合、トークンは有効です。 {"ok":false,"error_code":401,"description":"Unauthorized"} が返された場合、トークンの有効期限が切れています。

トークンの失敗の一般的な理由は次のとおりです。

• BotFather でトークンを手動でリセットする
• ボットは削除後に再作成されます
• 権限の変更により、Telegram によってトークンが取り消されました

トークンが更新された後、Webhook をリセットする必要がありますか?

**必要。 ** トークンを置き換えると、古いトークンに対応する Webhook 設定も無効になります。 Webhook を再バインドする必要があります。そうしないと、ボットはユーザー メッセージを受信できません。

TG-Staff コンソールでの手順:

1. app.tg-staff.comにログインし、対応するプロジェクトに入ります 2.「プロジェクト設定」→「ボット設定」をクリックします。
2. BotFather から取得した新しいトークンをトークン入力ボックスに貼り付けます。
3. [保存] をクリックすると、システムは Webhook を自動的にリセットします。

障害 2: Webhook の競合と接続の失敗

Webhook は、Telegram Bot と顧客サービス システムの間のブリッジです。ボットがユーザー メッセージを受信すると、Telegram サーバーは Webhook を通じて指定した URL にメッセージをプッシュします。複数のサービスが同時に同じ Webhook を占有する場合、競合が発生します。

Webhook の競合とは何ですか?検出方法は?

Webhook の競合とは、ボットの現在の Webhook アドレスが TG スタッフ以外の URL (他のカスタマー サービス プラットフォーム、カスタム スクリプト、テスト サーバーなど) を指していることを意味します。検出方法：

1. ブラウザでアクセスします: https://api.telegram.org/bot<你的Token>/getWebhookInfo
2. 返された url フィールドを確認します。フィールドが https://app.tg-staff.com/... 形式以外のアドレスを指している場合、競合が発生します。

Webhook の競合を解決する 2 つの方法

方法 1: TG-Staff コンソールでのワンクリック修復

プロジェクト設定ページで Webhook の競合が検出された場合、コンソールに警告プロンプトが表示されます。 「Webhook をリセット」ボタンをクリックすると、システムは古い設定を自動的にクリアし、正しいアドレスをバインドします。

方法 2: 手動でクリアしてから再バインド

自動修復が失敗した場合は、Telegram API を手動で呼び出して競合を解消できます。

https://api.telegram.org/bot<你的Token>/deleteWebhook

実行が成功すると、{"ok":true} を返します。次に、TG-Staff コンソールで Webhook バインディングを再トリガーします。

障害 3: エージェントがログインできない、またはセッションを表示できない

エージェントは顧客サービス システムの中核的な実行者です。エージェントがログインできない、またはログイン後にセッションが表示されないことを報告する場合、通常はアカウント ステータス、エージェント クォータ、プロジェクト権限の 3 つのレベルが関係します。

エージェントのログイン時に「アカウントがアクティブ化されていません」というメッセージが表示された場合はどうすればよいですか?

まず、管理者によってエージェントが「エージェント管理」から削除されているかどうかを確認してください。次に、現在のパッケージの座席割り当てが使い果たされているかどうかを確認します。各 TG-Staff パッケージの座席割り当ては次のとおりです (公式 Web サイトによる)。

パッケージの種類	座席割り当て	該当するシナリオ
無料トライアル	限定	テスト評価
通常版	3 エージェント	小規模チーム
プロフェッショナル版	20 エージェント	中規模から大規模のチーム

シート クォータがいっぱいの場合は、パッケージをアップグレードするか、非アクティブなシート クォータを解放する必要があります。

エージェントはログイン後にセッションを表示できません

これは最も一般的な構成エラーです。トラブルシューティングの手順:

1. プロジェクトの顧客サービス範囲を確認します: 管理者は、「プロジェクト設定」→「顧客サービス範囲」を入力し、エージェントがチェックされていることを確認します。
2. 転送ルール設定の表示: 転送ルールが「指定された顧客サービス」に設定されており、エージェントが含まれていない場合、セッションは受信されません。
3. エージェントのオンライン ステータスを確認: オフロード ルールが「オンライン優先」の場合、エージェントは新しいセッションを受信するためにオンラインを維持する必要があります。

障害 4: セッションのオフロード (ローテーション分散/オンライン優先) が機能しない

セッション オフロードは、顧客サービス システムがユーザーを適切なエージェントに自動的に割り当てるメカニズムです。 TG-Staff は、順番に割り当て (デフォルト、許可されたエージェントを順番にポーリング) と オンライン優先 (最初にオンライン エージェントに割り当て、すべてがオフラインになったら順番に割り当てにフォールバック) の 2 つの分散モードをサポートします。構成後にオフロードが有効にならない場合、通常は次の理由が考えられます。

ラウンドロビンとオンラインの優先順位: どちらを選択しますか?

特長	回転	オンライン優先
割り当てロジック	固定順序でのポーリング	まずはオンラインエージェントを見つけてください
該当するシナリオ	チームエージェントは全員オンライン	エージェントのオンライン時間は固定されていません
オフライン処理	オフラインエージェントをスキップ	すべてがオフラインの場合はフォールバックしてターン割り当てに戻ります

シャント障害のトラブルシューティング手順

1. エージェントのオンライン ステータスを確認: オンライン優先モードでは、すべてのエージェントがオフラインの場合、新しいセッションは割り当てられません
2. チェック項目カスタマー サービス範囲: 転送に参加しているすべてのエージェントが「カスタマー サービス範囲」内にいることを確認します。
3. 転送リンクが正しく使用されていることを確認します: 転送リンクは、Bot ネイティブ リンクではなく、TG-Staff (Standard Edition 以降のパッケージでサポートされています) によって生成される必要があります。ネイティブリンクは転送ロジックをトリガーしません

障害 5: 迂回リンク (マジック リンク) が異常にジャンプするか、属性に失敗します

転送リンク (マジック リンクとも呼ばれます) は、TG-Staff によって提供される公式のドメイン名の短縮リンクであり、広告トラフィックの帰属とマルチチャネル追跡に使用されます。ユーザーがリンクをクリックすると、システムは訪問者の IP、ブラウザ情報、URL パラメーターをキャプチャし、ボットにジャンプして会話を開始します。

ジャンプ例外の一般的な原因

• リンクの有効期限: 各転送リンクには有効期間があり、有効期限が切れた後はリダイレクトできません。
• パッケージの制限: 流用リンクは標準版以上のパッケージの機能であり、無料トライアルユーザーは使用できません。
• URL パラメータが切り詰められている: 広告リンクの utm_* パラメータが正しく結合されていない場合、アトリビューション データが欠落している可能性があります。

アトリビューションの失敗のトラブルシューティング方法

1. 転送リンクの形式を確認します。https://app.tg-staff.com/{code} 形式である必要があります。
2. 広告リンク パラメータを確認します。utm_source、utm_medium、utm_campaign、およびその他のパラメータがオフロード リンクの後に正しく接続されていることを確認します。
3. ジャンプ プロセスをテストします。ブラウザで転送リンクを手動で開き、ボットに正常にジャンプできることを確認します。

障害 6: メッセージの送信に失敗するか、自動翻訳が有効になりません

エージェントがメッセージの送信に失敗するか、自動翻訳が機能しません。これは通常、コンテンツ リスク制御の傍受、翻訳クォータの使い果たし、または機能スイッチが有効になっていないことに関連しています。

コンテンツリスク制御の傍受

プロフェッショナル バージョンのコンテンツ リスク制御機能は、エージェントがメッセージを送信する前に危険な単語を検出します。メッセージが危険なフレーズにヒットした場合、2 番目の確認ウィンドウがポップアップ表示されるか、送信が直接ブロックされます。トラブルシューティング方法:

・「内部統制管理」→「リスクフレーズ」の設定を確認し、合法的な内容が誤って傍受されていないか確認する

• Web3 プロジェクトの場合は、ウォレット アドレスの監視に注意してください。特定の TRC20/ERC20 アドレスがリスク フレーズに設定されている場合、エージェントはこのアドレスを含むメッセージを送信すると傍受されます。

自動翻訳が有効になりません

自動翻訳には次の 3 つの条件を満たす必要があります。

1. パッケージには翻訳クォータが含まれます（標準バージョンには AI 翻訳が含まれ、プロフェッショナルバージョンには Google プロ翻訳と DeepL プロ翻訳が追加されています）
2. 現在のセッションで変換スイッチがオンになっています (エージェント インターフェイスの右上隅)
3. その日の翻訳割り当てが使い果たされていない (残りの割り当てはコンソールで確認できます)

よくある質問

**Q: Bot Token をリセットすると、TG-Staff は自動的に更新されますか? ** 回答: いいえ。BotFather から新しいトークンを取得し、TG-Staff コンソールの「プロジェクト設定」で手動で更新する必要があります。更新後、システムは Webhook を自動的にリセットします。

**Q: Webhook が競合した場合、TG-Staff はプロンプトを表示しますか? ** 答え: はい。ボットをバインドしようとすると、Webhook が別のサービスを指していることが検出されると、コンソールに警告が表示されます。ワンクリックで競合をクリアして再バインドできます。

**Q: エージェントはログイン後にセッションを表示できません。理由は何ですか? ** 回答: 最も一般的な理由は、エージェントがプロジェクトの「カスタマー サービス スコープ」に追加されていないことです。管理者は、「プロジェクト設定 → 顧客サービス範囲」でエージェントをチェックし、転送ルールが有効になっていることを確認するように求められます。

**Q: 無料トライアル ユーザーは転用リンク (マジック リンク) を利用できますか? ** A: 利用できません。転用リンクは、Standard Edition 以降のパッケージの機能です。無料トライアル ユーザーは Bot ネイティブ リンクのみを使用でき、アトリビューション トラッキングを実装できません。

**Q: コンテンツ リスク コントロールはエージェントから送信された正規のメッセージを傍受します。どうすればよいですか? ** 回答: 管理者は、「内部統制管理 → リスク フレーズ」でトリガー ルールを調整または削除できます。誤ってインターセプトしてしまった場合でも、一時的に解除してからフレーズ構成を変更することが可能です。

結論とアクションの提案

Telegram カスタマー サービス システムを構築する場合、トークン、Webhook、エージェント、転送は最も障害が発生しやすい 4 つのリンクです。ほとんどの問題は、この記事で説明するトラブルシューティング方法を使用してすぐに解決できます。 TG-Staff を初めて使用する場合は、正式にリリースする前に、無料トライアル (3 日間) に登録し、テスト環境ですべてのプロセスを完了することをお勧めします。

推奨行動:

1. トライアルに登録します: app.tg-staff.com 今すぐ 3 日間の無料トライアルをお試しください
2. 詳細な操作ガイドについては、完全なドキュメントを確認してください: docs.tg-staff.com
3. カスタマー サービスに連絡する: 解決できない問題が発生した場合は、@tgstaff_robot に直接連絡してテクニカル サポートを依頼できます。

信頼性の高い Telegram カスタマー サービス システムを構築することは難しくありません。重要なのは、よくある障害を事前に理解し、トラブルシューティングの方法をマスターすることです。このガイドが、回り道を避け、顧客サービス システムを真にビジネスの成長に後押しする一助となることを願っています。