> ## 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. # WhatsApp アカウントプロキシ利用ガイド > Platform API guide - Ace Data Cloud WhatsApp アカウントプロキシは、**あなた自身が許可した WhatsApp アカウント**に接続し、既存のチャット、連絡先、メッセージをあなたの Agent に提供します。各デプロイインスタンスには、独立した接続、アクセストークン、永続ストレージがあります。サービス自体に AI は含まれず、自動返信、一斉送信、または誰かへの能動的な連絡は行いません。 > 本サービスは WhatsApp のリンク済みデバイス機能を使用しており、WhatsApp 公式の Business API ではありません。アカウントの接続方法は WhatsApp 公式のサポート対象外です。プロトコルの変更、デバイスの取り消し、またはアカウント制限により中断する可能性があります。所有するアカウントのみを接続し、WhatsApp の利用規約を遵守し、スパムメッセージまたは同意のない一括送信には使用しないでください。 ## デプロイと本人による認可 1. コンソールで「WhatsApp アカウントプロキシ」アプリケーションを作成し、サブスクリプションを有効にした後、デプロイをクリックします。インスタンスリソースはプラットフォームによって自動的に構成されます。 2. インスタンスの準備が完了したら、管理ページで QR コードを確認します。本人のスマートフォンで WhatsApp を開き、**設定 → リンク済みデバイス → デバイスをリンク**からスキャンしてください。自分の電話番号を入力してペアリングコードをリクエストし、スマートフォン側で確認することもできます。 3. 管理ページのステータスが「接続済み」に変わったら、専用 MCP アドレスと Bearer アクセストークンをコピーします。 4. アカウントからログアウトすると、リンク済みデバイスの取り消しとローカルセッションおよび履歴の消去が試行されます。ログアウト結果が不確かな場合は、先にスマートフォンの「リンク済みデバイス」で当該デバイスを取り消してください。インスタンスを破棄すると、その永続ボリュームは削除されます。 QR コードとペアリングコードは、アカウント本人だけに渡してください。通常の再起動では当該インスタンスのセッションが再利用されます。スマートフォン側でデバイスを取り消した後は、インスタンスが再度認可を要求します。 ## 認証と機能 `/health` と `/readyz` を除き、REST、MCP、スキャン、ペアリングの各インターフェースにはすべて `Authorization: Bearer <アクセストークン>` が必要です。トークンはリクエストヘッダーにのみ入れ、URL やログには入れないでください。`GET /api/capabilities` は、現在のインスタンスで実際にサポートされている操作と保持上限を示します。 現在サポートされているもの：アカウントと接続ステータス、リンク済みデバイスに同期されたチャットと連絡先、リアルタイムメッセージイベント、ローカルに保持されたメッセージの読み取り、テキストおよび 10 MiB 以下のメディアの送受信、引用返信、絵文字リアクション、既読マーク、ならびにアカウント権限と WhatsApp の現行ルールで許可される本人のメッセージ編集・取り消し、グループ情報および単一メンバー操作です。グループの変更は引き続き WhatsApp によりメンバー権限と管理者権限が検証されます。 **履歴範囲**：スマートフォン側からリンク済みデバイスに実際に同期されたメッセージと、プロキシのオンライン中に受信したメッセージのみを読み取れます。すべての過去のメッセージを取得できる保証はありません。ローカルには直近 5,000 件のメッセージと 2,000 件のイベントのみが保持されます。メディアメタデータが存在する場合でも、元のメディアはすでにダウンロードできない可能性があります。 ## MCP デプロイ管理ページでは `https://whatsapp-bot-<实例 ID>.app.acedata.cloud/mcp` が提供されます。Streamable HTTP とカスタムリクエストヘッダーをサポートする MCP クライアントでこのアドレスを設定し、同じ Bearer トークンを追加してください。MCP ツールには `whatsapp_capabilities`、`whatsapp_whoami`、`whatsapp_chats`、`whatsapp_contacts`、`whatsapp_messages`、`whatsapp_events`、`whatsapp_send`、`whatsapp_send_status`、`whatsapp_media`、`whatsapp_mark_read`、`whatsapp_group`、および `whatsapp_group_update` が含まれます。 Agent は自身のタスクに応じてメッセージを読み取ることができます。第三者へメッセージを送信する、メッセージを変更する、またはグループを変更する前には、ユーザーに具体的な対象と内容を確認させる必要があります。MCP を設定しても、送信が自動的に実行されることはありません。 ## REST の例 ```bash theme={null} BASE='https://whatsapp-bot-<实例 ID>.app.acedata.cloud' TOKEN='<管理页显示的访问令牌>' curl "$BASE/api/auth/status" -H "Authorization: Bearer $TOKEN" curl "$BASE/api/chats?limit=20" -H "Authorization: Bearer $TOKEN" curl "$BASE/api/chats/123%40s.whatsapp.net/messages?limit=20" -H "Authorization: Bearer $TOKEN" ``` **自分自身の既存のチャットまたは連絡先**にのみメッセージを送信してください。`target` には `/api/chats` または `/api/contacts` が返す JID を使用してください。任意の電話番号を使ったコールド送信はできません。まず本人が受信者と内容を確認してください。 ```bash theme={null} curl -X POST "$BASE/api/messages" \ -H "Authorization: Bearer $TOKEN" \ -H "Idempotency-Key: my-confirmed-message-20261004-1" \ -H 'Content-Type: application/json' \ -d '{"target":"123@s.whatsapp.net","action":"text","text":"你好"}' ``` `action` には `text`、`media`、`edit`、`revoke`、または `reaction` を使用できます。メディア送信では `media_base64` と `mime_type` を渡します。返信では `reply_to` を渡します。編集と取り消しでは、ローカルで確認できる本人の `message_id` を渡します。リアクションでは `message_id` と `emoji` を渡します。`GET /api/chats/{target}/messages/{id}/media` でメディアをダウンロードでき、`POST /api/chats/{target}/read` で既読としてマークできます。 送信には 8～128 文字の `Idempotency-Key` を必ず付ける必要があります。返される `message_id` は固定で、ステータスは `pending`、`accepted`、`unknown`、`delivered`、または `read` です。`accepted` はローカル接続が送信を受け付けたことのみを示し、**相手が受信したことを意味しません**。`unknown` が発生した場合は、`GET /api/sends/{Idempotency-Key}` とメッセージイベントを照会してください。同じメッセージを新しいキーで再送しないでください。重複送信の原因となります。プロキシは不確定な操作を自動再送しません。 送信記録は自動的に削除されません。100,000 件に達すると、古い冪等キーが削除された後の重複送信を防ぐため、インスタンスは新しい送信を拒否します（HTTP 507）。 ## リアルタイムイベント `GET /api/events?after=<前回の next_cursor>&wait_ms=25000` は最長 25 秒のロングポーリングをサポートします。`GET /api/events/stream?after=<カーソル>` は SSE を提供します。イベントには単調増加する `seq` が含まれます。レスポンス内の `next_cursor` は Agent の永続状態に保存してください。`gap=true` の場合、古いイベントが削除されたことを示します。現在のチャット状態を再取得し、`oldest_cursor` から継続してください。メッセージイベント、送信ステータス、接続ステータスはそれぞれ個別に報告されます。 ## よくあるステータス | HTTP / ステータス | 対処方法 | | - | - | | 401 | Bearer トークンとリクエストヘッダーを確認してください。 | | 404 | 対象のチャット、連絡先、またはメッセージが本インスタンスのローカル記録にありません。 | | 409 | アカウントが接続されていないか、同じ冪等キーが異なる内容に対応しています。 | | 413 | メディアが 10 MiB を超えています。 | | 403 / 429 | 操作が拒否されたか、レート制限が発生しました。送信時に発生した場合も、先に当該冪等キーの結果を確認してください。 | | 502 / 503 | 接続またはリモート操作に失敗しました。送信結果が不確かな場合は、先に操作ステータスとイベントを確認してください。 | 無制限の履歴、すべてのメディアの長期的な利用可能性、またはすべてのグループ操作が常に WhatsApp に受け入れられることは保証されません。特定のインスタンスを確認する必要がある場合は、まず `/api/auth/status` と `/api/capabilities` を確認してください。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.