> ## 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. # Leitfaden zur Nutzung des WhatsApp-Konto-Proxys > Platform API guide - Ace Data Cloud Der WhatsApp-Konto-Proxy verbindet sich mit **deinem von dir autorisierten WhatsApp-Konto** und stellt deinem Agenten bestehende Chats, Kontakte und Nachrichten bereit. Jede Bereitstellungsinstanz verfügt über eine unabhängige Verbindung, ein Zugriffstoken und persistenten Speicher. Der Dienst selbst enthält keine KI und antwortet nicht automatisch, versendet keine Massennachrichten und kontaktiert niemanden proaktiv. > Dieser Dienst nutzt die Fähigkeit verknüpfter WhatsApp-Geräte und nicht die offizielle WhatsApp Business API; die Art der Kontoanbindung wird von WhatsApp nicht offiziell unterstützt. Protokolländerungen, der Widerruf eines Geräts oder Kontobeschränkungen können zu Unterbrechungen führen. Verbinde nur Konten, die dir gehören, halte die WhatsApp-Bedingungen ein und nutze ihn nicht für Spam-Nachrichten oder massenhafte Sendungen ohne Einwilligung. ## Bereitstellung und eigene Autorisierung 1. Erstelle in der Konsole eine Anwendung „WhatsApp-Konto-Proxy“, aktiviere nach Abschluss des Abonnements die Bereitstellung. Die Instanzressourcen werden automatisch von der Plattform konfiguriert. 2. Nachdem die Instanz bereit ist, rufe auf der Verwaltungsseite den QR-Code auf. Öffne auf deinem eigenen Telefon WhatsApp **Einstellungen → Verknüpfte Geräte → Gerät verknüpfen** und scanne den Code. Du kannst auch deine eigene Telefonnummer eingeben, um einen Kopplungscode anzufordern, und ihn anschließend auf dem Telefon bestätigen. 3. Nachdem der Status auf der Verwaltungsseite zu „Verbunden“ wechselt, kopiere die exklusive MCP-Adresse und das Bearer-Zugriffstoken. 4. Das Abmelden vom Konto versucht, das verknüpfte Gerät zu widerrufen sowie die lokale Sitzung und den Verlauf zu löschen. Wenn das Ergebnis der Abmeldung ungewiss ist, widerrufe dieses Gerät zuerst unter „Verknüpfte Geräte“ auf dem Telefon; das Zerstören der Instanz entfernt ihr persistentes Volume. QR-Codes und Kopplungscodes dürfen nur dem Kontoinhaber gegeben werden. Ein normaler Neustart verwendet die Sitzung dieser Instanz erneut; nachdem das Gerät auf dem Telefon widerrufen wurde, fordert die Instanz erneut eine Autorisierung an. ## Authentifizierung und Fähigkeiten Mit Ausnahme von `/health` und `/readyz` erfordern REST-, MCP-, Scan- und Kopplungsschnittstellen alle `Authorization: Bearer `. Das Token gehört nur in den Anfrageheader, nicht in URLs oder Protokolle. `GET /api/capabilities` gibt die tatsächlich unterstützten Vorgänge und Aufbewahrungsgrenzen der aktuellen Instanz aus. Derzeit unterstützt: Konto- und Verbindungsstatus, mit dem verknüpften Gerät synchronisierte Chats und Kontakte, Echtzeit-Nachrichtenereignisse, das Lesen lokal gespeicherter Nachrichten, das Senden und Empfangen von Text und Medien bis 10 MiB, Antworten mit Zitat, Emoji-Reaktionen, Als-gelesen-Markieren sowie das Bearbeiten/Zurückrufen eigener Nachrichten, Gruppeninformationen und Einzelmitgliedsvorgänge, die durch Kontoberechtigungen und die aktuellen WhatsApp-Regeln erlaubt sind. Gruppenänderungen werden weiterhin von WhatsApp auf Mitgliedschafts- und Administratorberechtigungen geprüft. **Verlaufsumfang**: Es können nur Nachrichten gelesen werden, die tatsächlich vom Telefon auf das verknüpfte Gerät synchronisiert wurden, sowie Nachrichten, die während der Onlinezeit des Proxys empfangen wurden. Es kann nicht garantiert werden, dass alle alten Nachrichten verfügbar sind; lokal werden höchstens die letzten 5.000 Nachrichten und 2.000 Ereignisse aufbewahrt. Wenn Medienmetadaten vorhanden sind, können die Originalmedien dennoch möglicherweise nicht mehr heruntergeladen werden. ## MCP Die Bereitstellungs-Verwaltungsseite stellt `https://whatsapp-bot-<实例 ID>.app.acedata.cloud/mcp` bereit. Konfiguriere diese Adresse in einem MCP-Client, der Streamable HTTP und benutzerdefinierte Anfrageheader unterstützt, und füge dasselbe Bearer-Token hinzu. Die MCP-Tools umfassen `whatsapp_capabilities`, `whatsapp_whoami`, `whatsapp_chats`, `whatsapp_contacts`, `whatsapp_messages`, `whatsapp_events`, `whatsapp_send`, `whatsapp_send_status`, `whatsapp_media`, `whatsapp_mark_read`, `whatsapp_group` und `whatsapp_group_update`. Der Agent kann Nachrichten entsprechend seinen eigenen Aufgaben lesen; bevor Nachrichten an Dritte gesendet, Nachrichten geändert oder Gruppen geändert werden, sollte der Benutzer den konkreten Empfänger und Inhalt bestätigen. Die Konfiguration von MCP löst nicht eigenständig einen Versand aus. ## REST-Beispiele ```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" ``` Sende Nachrichten nur an**deine eigenen bestehenden Chats oder Kontakte**. `target` sollte die von `/api/chats` oder `/api/contacts` zurückgegebene JID verwenden; beliebige Telefonnummern dürfen nicht für Kaltakquise-Nachrichten verwendet werden. Lass den Empfänger und Inhalt zuerst vom Kontoinhaber bestätigen. ```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` kann `text`, `media`, `edit`, `revoke` oder `reaction` sein. Für das Senden von Medien werden `media_base64` und `mime_type` übergeben; für Antworten `reply_to`; für Bearbeiten und Zurückrufen wird eine lokal auffindbare eigene `message_id` übergeben; für Reaktionen werden `message_id` und `emoji` übergeben. Medien können über `GET /api/chats/{target}/messages/{id}/media` heruntergeladen und über `POST /api/chats/{target}/read` als gelesen markiert werden. Zum Senden muss ein 8–128 Zeichen langer `Idempotency-Key` angegeben werden. Die zurückgegebene `message_id` ist fest, der Status lautet `pending`, `accepted`, `unknown`, `delivered` oder `read`. `accepted` bedeutet lediglich, dass die lokale Verbindung den Versand akzeptiert hat, **nicht, dass der Empfänger ihn erhalten hat**. Bei `unknown` frage `GET /api/sends/{Idempotency-Key}` und die Nachrichtenereignisse ab; verwende keinen neuen Schlüssel, um dieselbe Nachricht erneut zu senden, damit Duplikate vermieden werden. Der Proxy wiederholt unsichere Vorgänge nicht automatisch. Sendelogs werden nicht automatisch bereinigt; nach Erreichen von 100.000 Einträgen lehnt die Instanz neue Sendungen ab (HTTP 507), um doppelte Sendungen zu vermeiden, nachdem alte Idempotenzschlüssel gelöscht wurden. ## Echtzeitereignisse `GET /api/events?after=&wait_ms=25000` unterstützt Long Polling für höchstens 25 Sekunden; `GET /api/events/stream?after=` stellt SSE bereit. Ereignisse enthalten ein monoton steigendes `seq`. Das `next_cursor` in der Antwort sollte im persistenten Zustand des Agenten gespeichert werden; wenn `gap=true`, bedeutet dies, dass alte Ereignisse bereinigt wurden. Der aktuelle Chatstatus sollte erneut abgerufen und ab `oldest_cursor` fortgesetzt werden. Nachrichtenereignisse, Sendestatus und Verbindungsstatus werden unabhängig gemeldet. ## Häufige Status | HTTP / Status | Vorgehensweise | | - | - | | 401 | Bearer-Token und Anfrageheader prüfen. | | 404 | Zielchat, Kontakt oder Nachricht ist nicht im lokalen Datensatz dieser Instanz vorhanden. | | 409 | Konto ist nicht verbunden, oder derselbe Idempotenzschlüssel entspricht einem anderen Inhalt. | | 413 | Medium überschreitet 10 MiB. | | 403 / 429 | Vorgang wurde abgelehnt oder hat eine Ratenbegrenzung ausgelöst; wenn dies beim Senden geschieht, muss dennoch zuerst das Ergebnis dieses Idempotenzschlüssels geprüft werden. | | 502 / 503 | Verbindung oder Remote-Vorgang fehlgeschlagen; wenn das Sendeergebnis ungewiss ist, zuerst Vorgangsstatus und Ereignisse prüfen. | Es wird weder unbegrenzter Verlauf noch die langfristige Verfügbarkeit aller Medien garantiert, noch dass alle Gruppenvorgänge stets von WhatsApp akzeptiert werden. Wenn eine konkrete Instanz geprüft werden muss, sieh zuerst unter `/api/auth/status` und `/api/capabilities` nach. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.