🤖HermesBlog
Hermes メッセージングプラットフォーム · パート 318/9/2026

WeCom コールバックモード — カスタムアプリ

WeCom コールバックモード — カスタムアプリ — 公式ドキュメントに基づくわかりやすいガイド

まるで、AIアシスタント専用のオフィスメールボックスを設置するようなものだと思ってください。グループチャットに紛れ込むのではなく、専用のデスクを与えられ、そこに人が直接立ち寄ってメッセージを残せる、そんなイメージです。

messaging-wecom-callback

何がそんなに違うのか？

Hermes Agent は、WeCom（エンタープライズWeChat）に接続する2つの方法を提供します。Bot モードは、グループチャットに参加する気さくなアシスタントのようなもので、セットアップは簡単ですが、機能は限られています。コールバックモード はこれとは異なり、従業員のWeComサイドバーに公式アプリと同じように表示されるカスタムアプリを構築します。ネイティブな見た目で、複数企業をサポートし、暗号化されたメッセージを安全に処理します。

その代償として、メッセージを受信するための公開サーバーが必要になります。ただし、心配は無用です。テスト目的であれば、ngrok のような単純なトンネルで十分機能します。

実際の仕組み

流れを平易な言葉で説明すると、次のようになります。

  1. 誰かがWeComのカスタムアプリにメッセージを送信します。
  2. WeComはそのメッセージを暗号化し、サーバーのHTTPエンドポイントに送信します。
  3. Hermesはそれを復号化し、AIエージェント用にキューに入れ、すぐにWeComへ「受信しました」と応答します（これは静かに行われ、ユーザーにはまだ何も表示されません）。
  4. エージェントは（タスクに応じて）3〜30分間思考します。
  5. HermesはWeComのメッセージAPIを使用して、応答をプロアクティブに送信します。

ポーリングも遅延もありません。クリーンで非同期な会話が実現します。

ステップバイステップのセットアップ

1. WeCom管理コンソールでアプリを作成する

WeCom管理コンソール にログインし、アプリケーション → アプリの作成 に進みます。 Corp ID（コンソール上部に表示）を控え、Corp Secret を作成します。 アプリの概要ページで、Agent ID を取得します。

メッセージの受信 セクションで、以下を設定します。

  • URL: http://YOUR_PUBLIC_IP:8645/wecom/callback
  • Token: ランダムなものを生成
  • EncodingAESKey: 43文字のキーを生成

2. 環境変数を設定する

.env ファイルに以下を追加します。

WECOM_CALLBACK_CORP_ID = your-corp-id
WECOM_CALLBACK_CORP_SECRET = your-corp-secret
WECOM_CALLBACK_AGENT_ID = 1000002
WECOM_CALLBACK_TOKEN = your-callback-token
WECOM_CALLBACK_ENCODING_AES_KEY = your-43-char-aes-key

# オプション
WECOM_CALLBACK_PORT = 8645
WECOM_CALLBACK_ALLOWED_USERS = user1,user2

3. ゲートウェイを起動する

hermes gateway

注: hermes gateway install を実行してサービスを登録した後にのみ、hermes gateway start を使用してください。

コールバックアダプターは、ポート8645でHTTPサーバーを起動します。WeComは GET リクエストでURLを検証し、その後 POST でメッセージを送信し始めます。

設定リファレンス

これらの設定は、config.yaml の platforms.wecom_callback.extra でも行えます。

設定 デフォルト 説明
corp_id — 必須。WeComのCorp ID
corp_secret — 必須。アプリのシークレット
agent_id — 必須。アプリのAgent ID
token — 必須。コールバック検証トークン
encoding_aes_key — 必須。43文字のAESキー
host 未設定（デュアルスタック） HTTPサーバーのバインドアドレス
port 8645 コールバックサーバーのポート

まとめ

WeComコールバックモードは、Hermesをエンタープライズワークフローに統合するための「公式」な方法です。Botモードよりもセットアップは複雑ですが、その見返りとして、ユーザーにとって洗練されたファーストクラスのアプリ体験が得られます。

実用的なヒント: 実際のサーバーを公開する前に、まず ngrok から始めましょう。ngrok http 8645 を実行し、そのURLをWeComコンソールで使用して、単一のユーザーでテストします。動作が確認できたら、本番サーバーに切り替え、WECOM_CALLBACK_ALLOWED_USERS をチームメンバーに限定してロックダウンします。それでは、素晴らしい構築を！

📖 公式ドキュメント

この記事は Hermes Agent の公式ドキュメントに基づいています：公式ドキュメント › user-guide/messaging/wecom-callback

← すべての記事に戻る