WeCom

最終更新 2026/10/07

1. 前提条件

• WeCom管理コンソールの権限があり、スマートボットを作成できること。OAuthを使用する場合は、企業の自社開発アプリも作成する必要があります。
• Agentic Engineの「システム管理 → チャンネル管理」の権限を持っていること。
• Agentic Engineのチャンネル管理機能が有効になっていること。
• デプロイ先のサーバーから、WeCom公式のロングコネクションアドレス wss://openws.work.weixin.qq.com にアクセスできること。
• メンバーのOAuth連携を使用する場合は、プラットフォームをHTTPSでユーザーに公開し、利用可能なパブリックドメインを用意しておく必要があります。

2. WeComのスマートボットを作成して認証情報を取得する

WeCom管理コンソールにログインし、次の手順で設定します：

1. 「Security and Management」->「Management Tools」に進み、「Intelligent Bot」を見つけて「Create Bot」->「Create manually」をクリックします。
2. 一番下までスクロールして Create in API mode を選択し、接続方式で Use persistent connection を選択します。
3. ボットの名前、紹介、表示範囲を入力し、設定を保存します。
4. API設定エリアで次の認証情報をコピーし、大切に保管します：

WeComのフィールド	プラットフォームのフィールド	説明
Bot ID	Bot ID	スマートボットの一意の識別子。ロングコネクションの認証に使用します。
Secret	Bot Secret	スマートボットのシークレット。安全な場所にのみ保管し、コード、チケット、チャット履歴には書き込まないでください。

ヒント

ボットのパブリックなコールバックURLを設定する必要はありません：Agentic Engineが自らWebSocketのロングコネクションを確立し、Bot IDとBot Secretで認証を行います。

任意：メンバーOAuth用の自社開発アプリを作成する

OAuthは、ボットがメッセージを送受信するうえで必須ではありません。ユーザーがブラウザでWeComのメンバーIDをワンクリックで連携できるようにする場合にのみ、同じ企業内で自社開発アプリを作成する必要があります。

1. WeCom管理コンソールで企業の自社開発アプリを作成し、使用するメンバーをアプリの表示範囲に追加します。
2. 企業とアプリの認証情報を控えておきます：

WeComのフィールド	プラットフォームのフィールド	説明
Company ID	Corp ID	通常は ww で始まり、企業情報で確認できます。
AgentId	Agent ID	自社開発アプリのアプリID。
Secret	Corp Secret	自社開発アプリのSecret。サーバー側でメンバーの身元を取得するために使用します。

必須：信頼できるドメインとURL（ドメイン）の主体検証を完了する

WeCom OAuthで使用するコールバックドメインは、事前に自社開発アプリの信頼できるドメインとして設定する必要があります。信頼できるドメインを保存する前に、WeComがドメインの所有権とドメインのICP届出主体を同時にチェックすることがあり、両方とも通過する必要があります。

1. 「WeCom Admin Console → App Management → Self-built → 対象アプリ → Web Authorization and JS-SDK」に進み、「Set Trusted Domain」をクリックします。
2. プラットフォームに実際にアクセスするドメイン（例：agent.example.com）を入力します。ドメインのみを入力し、https://、ポート、パスは含めません。サブドメインを使用する場合は、実際のサブドメインごとに個別に設定します。
3. 「Apply for Domain Verification」をクリックするか、ページの案内に従ってWeComが生成した WW_verify_*.txt 検証ファイルをダウンロードします。
4. ファイル名と内容を変更せずに、ファイルをそのドメインのWebサイトのルートディレクトリに配置します。ブラウザから直接アクセスできることを確認します：

域名所有权校验文件

https://agent.example.com/WW_verify_xxxxxxxxxxxx.txt

1. アクセスすると検証ファイルの内容がそのまま返される必要があります。ログインページへのリダイレクト、認証によるブロック、フロントエンドのSPAページの返却が起きてはいけません。
2. WeCom管理コンソールに戻り、「Domain ownership verification file uploaded」にチェックを入れて保存します。ファイルにアクセスできるのに失敗する場合は、DNS/CDNのキャッシュを確認し、しばらくしてから再試行します。

警告

URL主体検証：信頼できるドメインのICP届出主体は、現在のWeComの認証/検証主体と一致しているか、WeComが認める関連関係にある必要があります。「URL主体検証に失敗しました」や「ドメインの主体が一致しません」と表示された場合、アプリのコードで回避することはできません。主体が一致するICP届出済みのドメインに切り替えるか、先にICP届出と主体の関連付けを済ませてから設定してください。

構成項目	例	要件
信頼できるドメイン	agent.example.com	WeCom管理コンソールにはホスト名のみを入力
検証ファイルURL	https://agent.example.com/WW_verify_xxxxxxxxxxxx.txt	ドメインのルートディレクトリに配置し、ファイルの内容をそのまま返す
OAuthコールバックURL	https://agent.example.com/agent/api/wecom-oauth/callback	例は /agent サブパスを使用するデプロイの場合
オリジンのホワイトリスト	ALLOWED_ORIGINS=https://agent.example.com	プロトコルとホスト名を入力し、パスは含めない

ヒント

2つのURLを混同しないでください：検証ファイルはドメインのルートディレクトリに置く必要があります。OAuthコールバックは引き続き /agent/api/wecom-oauth/callback を使用します。両者のパスは異なりますが、ホスト名は信頼できるドメインと一致している必要があります。

1. 信頼できるドメイン、所有権、主体の検証が完了したら、次のOAuthコールバックURLにブラウザから正常にアクセスできることを確認します：

未配置子路径时

https://<your-domain>/agent/api/wecom-oauth/callback

本番環境では、認可元のホワイトリストを設定することを推奨します。複数のオリジンは半角カンマで区切ります：

ALLOWED_ORIGINS=https://<your-domain>

3. プラットフォームでWeComチャネルを追加する

管理者がAgentic Engineにログインし、「システム管理」→「チャンネル管理」に進みます：

1. 「新規チャンネル」をクリックし、チャンネルタイプで WeCom を選択します。
2. 次の構成項目を入力します：

構成項目	必須	説明
チャンネル名	必須	表示名。例：「WeCom チャットボット」。
Bot ID	必須	WeComスマートボットのBot ID。
Bot Secret	必須	WeComスマートボットのSecret。
メンバー OAuth バインドを有効化	任意	ONにすると、ブラウザでの認証による連携が優先されます。OFFにしても連携コードは引き続き使用できます。
Corp ID	条件付き必須	OAuthを有効にする場合は必須です。
Agent ID	条件付き必須	OAuthを有効にする場合は必須です。
Corp Secret	条件付き必須	OAuthを有効にする場合は必須です。
デフォルトモデル	任意	選択しない場合は、システム全体のデフォルトモデルを使用します。
システムプロンプト	任意	このチャネルのAgent会話にのみ適用されます。

1. 「保存」をクリックし、チャンネルの「有効」スイッチをオンにします。
2. チャネルのステータスが「オンライン」になったことを確認します。「オフライン」または「エラー」のままの場合は、本ドキュメントのトラブルシューティングの章に従って確認します。

ヒント

チャンネルタイプごとに作成できるインスタンスは1つのみです。Secretは暗号化して保存され、再表示されません。チャネルの編集時にSecretを空欄のままにすると、元の値が保持されます。OAuthをOFFにすると、OAuthの認証情報一式が削除されます。

4. ユーザーがWeComアカウントを連携する

方法1：OAuth認証による連携

1. ユーザーがAgentic Engineにログインし、左下のユーザーアバターをクリックします。
2. アカウントメニューで「WeCom」を見つけ、「連携」をクリックします。
3. WeComのメンバー認証ページが開くので、同じ企業の内部メンバーのアカウントで認証を完了します。
4. 認証に成功するとウィンドウが自動的に閉じ、メニューのWeComのステータスが「連携済み」に変わります。

方法2：ワンタイム連携コード

OAuthが有効になっていない場合、またはプラットフォームにHTTPでアクセスしている場合は、自動的に連携コードが使用されます：

1. 左下のユーザーアバターをクリックし、「WeCom」の行で「連携」をクリックします。
2. システムが生成した6桁の連携コードをコピーします。連携コードの有効期間は10分間で、1回しか使用できません。
3. WeComでスマートボットに次のいずれかのコマンドを送信します：

绑定 ABC234
+bind ABC234

ボットから「WeCom アカウントを連携しました」と返信されると、プラットフォームのメニューが自動的に「連携済み」に更新されます。同じWeComメンバーで、他のAgentic Engineユーザーの有効な連携を上書きすることはできません。

連携解除

1. 左下のユーザーアバターをクリックし、「WeCom」の行で「連携解除」をクリックします。
2. 連携解除を確定すると、ステータスが「未連携」に変わります。Agentic Engineアカウントを変更する場合は、先に元のアカウントの連携を解除する必要があります。

5. よくある質問

チャネルのステータスが「オフライン」または「エラー」になる

• Bot IDとBot Secretが同じスマートボットのものであること、コピー時に余分な空白が入っていないことを確認します。
• WeCom管理コンソールでボットが無効化されておらず、APIモードとロングコネクションが選択されていることを確認します。
• サーバーから wss://openws.work.weixin.qq.com にアクセスできることを確認します。
• Secretを再生成すると、古い値は無効になります。チャネルを編集して新しいSecretを入力し、再度有効にしてください。

OAuthが有効になっていない、または設定が不完全と表示される

• WeComチャネルが有効になっていて、「メンバー OAuth バインドを有効化」スイッチがONになっていることを確認します。
• Corp ID、Agent ID、Corp Secretがすべて入力されていて、同じ企業の自社開発アプリのものであることを確認します。
• 自社開発アプリの表示範囲に現在のメンバーが含まれていることを確認します。

OAuthコールバックに失敗する

• コールバックのドメイン、プロトコル、ポート、パスが、プラットフォームの実際のアクセスアドレスと完全に一致していることを確認します。
• NEXT_PUBLIC_BASE_PATH を使用している場合は、コールバックURLにそのサブパスを含める必要があります。
• ALLOWED_ORIGINS を設定している場合は、現在のアクセス元がホワイトリストに含まれていることを確認します。
• OAuth連携には企業の内部メンバーを使用する必要があります。外部連絡先は連携できません。

連携コードが無効、または期限切れになっている

• 連携コードを再生成し、10分以内に使用します。
• コマンドの形式が 绑定 ABC234 または +bind ABC234 であることを確認します。
• 連携コードは1回しか使用できません。使用済みの連携コードを再送信することはできません。

ボットはテキストに返信できるが、添付ファイルを読み取れない

• channel.wecom.fileUploads.enabled が無効になっていないことを確認します。
• ファイルタイプがサポートされていて、1ファイルあたりのサイズと1メッセージあたりの添付ファイル数が設定の上限を超えていないことを確認します。
• サンドボックスの添付ファイルストレージとファイルAPIが正常に使用できることを確認します。

テンプレートカードをクリックしても応答がない

• チャネルのロングコネクションがオンラインであることを確認します。
• カードに対応するインタラクションが期限切れになっておらず、まだ回答されていないこと、また現在クリックしているユーザーが連携済みのユーザー本人であることを確認します。
• WeComが求める時間内に、サーバーがカードを処理して更新できているかを確認します。

---

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

• 他のプラットフォームの接続手順を確認する：チャンネル管理。
• チャネル接続と連携の全体的な流れを確認する：チャネルの概要と連携。
• 使用するAgentを設定する：Agent。
• プラットフォーム内での会話の使い方を確認する：会話。