> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# WeCom ボット

> Platform API guide - Ace Data Cloud

自分専用の WeCom アカウントインスタンスをデプロイし、スマートフォンの WeCom で QR コードをスキャンしてログインし、REST API または MCP を通じてアカウント、連絡先、会話、およびローカル同期メッセージを読み取ります。インスタンスは通常の WeCom アカウントに対応し、オンプレミスサーバーや企業メールドメインの設定は不要です。

現在は Alpha です。アカウント読み取りは実際の会話での検証を完了しています。本人へのテキスト送信およびイベント読み戻しは実際の受け入れを完了しています。その他の連絡先、グループ操作、および新しいインスタンスの復元は、引き続きデプロイ環境での受け入れを完了する必要があります。メディア送信、引用返信、実際の @、グループメンバー管理、および配達確認はまだ公開されていません。インスタンスの `/api/capabilities` の戻り値を基準としてください。

## デプロイとログイン

Deployment カテゴリでサービスを有効化し、インスタンスの期間プランを選択します。デプロイ後、管理ページを開き、アカウント本人の WeCom でスキャンしてください。スマートフォンでの確認またはその他のログイン手順が必要な場合は、リモートデスクトップを開き、そのインスタンスのデスクトップパスワードを入力してください。API 認証情報とデスクトップパスワードは独立しています。ログイン情報はインスタンスのディスクに保存され、コンテナを再作成してもディスクは保持されます。ディスクを削除するとローカルセッションが削除されます。

各インスタンスは個別に課金され、購入済みの期間に応じて稼働します。REST / MCP 呼び出しにはメッセージごとの追加料金はかかりません。実際の価格はプランページを基準としてください。現在は WeChat ボットの期間プランをデフォルトの参考としており、正式公開前に実行リソースと合わせて価格確認を完了する必要があります。

## API と MCP

管理ページ内のインスタンス API アドレスを使用し、すべてのアカウントインターフェースで `Authorization: Bearer <インスタンス API token>` を付与します。これらのパスは専用インスタンスに属しており、共有 API ゲートウェイではありません。MCP アドレスはインスタンスアドレスに `/mcp/` を追加したものであり、同じ Bearer token を使用します。

| インターフェース | 役割 |
| - | - |
| `GET /api/status`、`GET /api/auth/status` | アカウントの準備状況と機能一覧 |
| `GET /api/auth/qr` | 現在のログイン QR コード PNG Base64 |
| `GET /api/account` | 現在のアカウント |
| `GET /api/contacts?kind=all` | 社内同僚および外部連絡先。internal / external を指定可能 |
| `GET /api/conversations` | ローカル会話。元の会話 ID を保持 |
| `GET /api/messages` | ローカル同期メッセージ。conversation\_id、after\_rowid、limit パラメータ |
| `POST /api/search` | 連絡先、会話、およびローカルテキスト検索 |
| `POST /api/messages` | テキスト送信の非同期タスク。Idempotency-Key の指定が必須 |
| `POST /api/messages/send` | 同じ送信エントリ。単一または複数の対象をサポート |
| `GET /api/groups/{conversation_id}` | ローカル同期されたグループ情報およびメンバー |
| `GET /api/tasks` | 最近のタスクおよび各対象の結果 |
| `GET /api/tasks/{id}` | 送信結果の照会 |
| `POST /api/tasks/{id}/cancel` | まだ開始していないタスクをキャンセル |
| `POST /api/runtime/pause`、`POST /api/runtime/resume` | 自動化を一時停止。本人確認後に再開 |
| `GET /api/diagnostics`、`GET /api/diagnostics/screenshot` | インスタンス状態と現在の画面。いずれも認証が必要 |
| `GET /api/events?after=0` | 再開可能なカーソルを持つメッセージイベント |
| `WS /ws` | メッセージイベントストリーム。Bearer 認証 |

送信ボディには `target`、`type: "text"`、および `text` が含まれます。`target` は会話 ID、連絡先 ID、企業ユーザー ID、または一意の完全名を受け付けます。ID を優先して使用してください。表示名でなお一意に特定できない場合、インスタンスは操作を拒否し、対象を推測しません。ローカル会話がない連絡先については、まずクライアント経由で会話を開き、実際の会話 ID を確認してから送信します。リクエストヘッダーの `Idempotency-Key` は 8～128 文字の英字、数字、または `_.:-` です。同一操作への重複リクエストでは、同じキーと同じリクエストボディを再利用する必要があります。

`target` を `targets` 配列に置き換えると、明確に指定された 1～50 件の対象へ順番に送信できます。両方を同時に指定することはできません。すべての対象は先にID解決を完了し、同一オブジェクトを指す異なる別名は拒否されます。ある対象で失敗した後は後続の送信を停止し、タスク結果には対象ごとに `succeeded`、`failed`、`unknown`、または `not_attempted` が記録されます。部分的な成功を完全な成功として扱わないでください。このフローは、デプロイ環境において指定された連絡先での実際の受け入れも完了する必要があります。

タスクは queued、running、submitting、succeeded、failed、unknown、または cancelled の状態になる可能性があります。`succeeded` は、送信後に対応する会話記録で正確なテキストおよびサーバーメッセージ ID が見つかったことを意味します。`delivered` は依然として null であり、相手が受信したことを意味しません。unknown は結果が不明確であることを示します。履歴を確認し、新しいキーで送信を繰り返さないでください。インスタンスは中断したタスクを自動的に再送しません。

履歴にはクライアントがすでに同期した内容のみが含まれ、すべての履歴を保証するものではありません。非テキストメッセージは unknown タイプとして返される場合があり、添付ファイルのダウンロードはまだ公開されていません。イベントは直近 10,000 件を保持し、`gap` はカーソルが保持ウィンドウを超えたことを示します。初回接続時に、古い履歴を新しいメッセージとして再生することはありません。

メッセージ履歴内の `server_accepted` と `server_id` は、サーバーがローカルメッセージを受け入れたかどうかの照合に使用できます。ローカル記録のみが存在し、サーバー ID がない場合、送信成功と認定することはできません。これらのフィールドは、受信者が受信または既読したことを意味しません。イベント記録は生成時の状態を保持しており、現在の確認状態を照会するにはメッセージ履歴インターフェースを使用してください。

## アカウントと認証情報

本人が操作する権限を持つアカウントのみでログインしてください。API token は信頼できるアプリケーションに設定してください。これは当該インスタンスのアカウントデータにアクセスできます。パスワード、QR コード、またはチャットのスクリーンショットを公開場所に掲載しないでください。インスタンスを一時停止すると、リアルタイムイベントが中断されます。アカウントからログアウトした場合、またはスマートフォン側でデバイスを削除した場合は、再ログインが必要です。

現在、テキスト入力は単一行のみをサポートしており、改行は送信前に明示的に拒否されます。クライアントがセキュリティ認証または再ログインを要求した場合、アカウント本人がリモートデスクトップ上で完了する必要があります。インスタンスが認証を回避することはありません。認証中断後のタスクは unknown を返す可能性があります。まずメッセージ記録を照会し、新しい冪等キーで再送しないでください。

セキュリティ認証のプロンプト、アカウントのログアウト、または変更が検出されると、自動化キューは永続的に一時停止されます。スマートフォンでの認証完了後、インスタンスコンソールの「認証後に再開」から、まだ実行されていないタスクを続行できます。すでに送信済みで結果が不確かなタスクは再送されません。通常のリモートワークでも WeCom のセキュリティ認証がトリガーされる場合があります。公式説明にある、認証後 24 時間は再ロックされないウィンドウは、検知がなくなったことを意味せず、インスタンスが長期無人運用を保証できることも意味しません。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.