Zalo (Bot-API)

Status: Experimentell. DMs werden unterstützt; Gruppenbehandlung ist mit expliziten Gruppenrichtlinien verfügbar.

Plugin erforderlich

Zalo wird als Plugin ausgeliefert und ist nicht in der Kerninstallation enthalten.

  • Installation über CLI: openclaw plugins install @openclaw/zalo
  • Oder wähle Zalo während des Onboardings und bestätige die Installationsaufforderung
  • Details: Plugins

Schnelleinrichtung (Einsteiger)

  1. Installiere das Zalo-Plugin:
    • Aus einem Quell-Checkout: openclaw plugins install ./extensions/zalo
    • Von npm (falls veröffentlicht): openclaw plugins install @openclaw/zalo
    • Oder wähle Zalo im Onboarding und bestätige die Installationsaufforderung
  2. Setze den Token:
    • Umgebungsvariable: ZALO_BOT_TOKEN=...
    • Oder Konfiguration: channels.zalo.botToken: "...".
  3. Starte das Gateway neu (oder schließe das Onboarding ab).
  4. DM-Zugang ist standardmäßig Pairing; genehmige den Pairing-Code beim ersten Kontakt.

Minimale Konfiguration:

{
  channels: {
    zalo: {
      enabled: true,
      botToken: "12345689:abc-xyz",
      dmPolicy: "pairing",
    },
  },
}

Was es ist

Zalo ist eine auf Vietnam fokussierte Messaging-App; die Bot-API ermöglicht es dem Gateway, einen Bot für 1:1-Unterhaltungen zu betreiben. Sie eignet sich gut für Support oder Benachrichtigungen, bei denen du deterministisches Routing zurück zu Zalo möchtest.

  • Ein Zalo-Bot-API-Kanal, der vom Gateway betrieben wird.
  • Deterministisches Routing: Antworten gehen zurück zu Zalo; das Modell wählt niemals den Kanal.
  • DMs teilen sich die Hauptsession des Agenten.
  • Gruppen werden mit Richtliniensteuerung unterstützt (groupPolicy + groupAllowFrom) und sind standardmäßig auf Fail-Closed-Allowlist-Verhalten eingestellt.

Einrichtung (Schnellweg)

1) Bot-Token erstellen (Zalo Bot Platform)

  1. Gehe zu https://bot.zaloplatforms.com und melde dich an.
  2. Erstelle einen neuen Bot und konfiguriere seine Einstellungen.
  3. Kopiere den Bot-Token (Format: 12345689:abc-xyz).

2) Token konfigurieren (Umgebungsvariable oder Konfiguration)

Beispiel:

{
  channels: {
    zalo: {
      enabled: true,
      botToken: "12345689:abc-xyz",
      dmPolicy: "pairing",
    },
  },
}

Umgebungsvariable: ZALO_BOT_TOKEN=... (funktioniert nur für das Standardkonto).

Multi-Account-Unterstützung: Verwende channels.zalo.accounts mit Pro-Konto-Tokens und optionalem name.

  1. Starte das Gateway neu. Zalo startet, wenn ein Token aufgelöst wird (Umgebungsvariable oder Konfiguration).
  2. DM-Zugang ist standardmäßig Pairing. Genehmige den Code, wenn der Bot zum ersten Mal kontaktiert wird.

Funktionsweise (Verhalten)

  • Eingehende Nachrichten werden in den gemeinsamen Kanalumschlag mit Medien-Platzhaltern normalisiert.
  • Antworten werden immer an denselben Zalo-Chat zurückgeleitet.
  • Standardmäßig Long-Polling; Webhook-Modus verfügbar mit channels.zalo.webhookUrl.

Limits

  • Ausgehender Text wird auf 2000 Zeichen aufgeteilt (Zalo-API-Limit).
  • Medien-Downloads/-Uploads sind begrenzt durch channels.zalo.mediaMaxMb (Standard 5).
  • Streaming ist standardmäßig blockiert, da das 2000-Zeichen-Limit Streaming weniger nützlich macht.

Zugriffssteuerung (DMs)

DM-Zugang

  • Standard: channels.zalo.dmPolicy = "pairing". Unbekannte Absender erhalten einen Pairing-Code; Nachrichten werden ignoriert, bis sie genehmigt sind (Codes verfallen nach 1 Stunde).
  • Genehmigung über:
    • openclaw pairing list zalo
    • openclaw pairing approve zalo <CODE>
  • Pairing ist der Standard-Token-Austausch. Details: Pairing
  • channels.zalo.allowFrom akzeptiert numerische Benutzer-IDs (keine Benutzernamen-Suche verfügbar).

Zugriffssteuerung (Gruppen)

  • channels.zalo.groupPolicy steuert die Gruppeneingangsverarbeitung: open | allowlist | disabled.
  • Standardverhalten ist Fail-Closed: allowlist.
  • channels.zalo.groupAllowFrom beschränkt, welche Absender-IDs den Bot in Gruppen auslösen können.
  • Wenn groupAllowFrom nicht gesetzt ist, fällt Zalo für Absenderprüfungen auf allowFrom zurück.
  • groupPolicy: "disabled" blockiert alle Gruppennachrichten.
  • groupPolicy: "open" erlaubt jedes Gruppenmitglied (Mention-gated).
  • Laufzeithinweis: Wenn channels.zalo vollständig fehlt, fällt die Laufzeit sicherheitshalber auf groupPolicy="allowlist" zurück.

Long-Polling vs. Webhook

  • Standard: Long-Polling (keine öffentliche URL erforderlich).
  • Webhook-Modus: Setze channels.zalo.webhookUrl und channels.zalo.webhookSecret.
    • Das Webhook-Secret muss 8-256 Zeichen lang sein.
    • Die Webhook-URL muss HTTPS verwenden.
    • Zalo sendet Events mit dem Header X-Bot-Api-Secret-Token zur Verifizierung.
    • Das Gateway-HTTP verarbeitet Webhook-Anfragen unter channels.zalo.webhookPath (standardmäßig der Webhook-URL-Pfad).
    • Anfragen müssen Content-Type: application/json (oder +json-Medientypen) verwenden.
    • Doppelte Events (event_name + message_id) werden für ein kurzes Wiederholungsfenster ignoriert.
    • Burst-Traffic wird pro Pfad/Quelle ratenbegrenzt und kann HTTP 429 zurückgeben.

Hinweis: getUpdates (Polling) und Webhook schließen sich laut Zalo-API-Dokumentation gegenseitig aus.

Unterstützte Nachrichtentypen

  • Textnachrichten: Vollständige Unterstützung mit 2000-Zeichen-Chunking.
  • Bildnachrichten: Eingehende Bilder herunterladen und verarbeiten; Bilder via sendPhoto senden.
  • Sticker: Protokolliert, aber nicht vollständig verarbeitet (keine Agent-Antwort).
  • Nicht unterstützte Typen: Protokolliert (z. B. Nachrichten von geschützten Benutzern).

Fähigkeiten

FeatureStatus
DirektnachrichtenUnterstützt
GruppenUnterstützt mit Richtliniensteuerung (standardmäßig Allowlist)
Medien (Bilder)Unterstützt
ReaktionenNicht unterstützt
ThreadsNicht unterstützt
UmfragenNicht unterstützt
Native BefehleNicht unterstützt
StreamingBlockiert (2000-Zeichen-Limit)

Zustellziele (CLI/Cron)

  • Verwende eine Chat-ID als Ziel.
  • Beispiel: openclaw message send --channel zalo --target 123456789 --message "hi".

Fehlerbehebung

Bot antwortet nicht:

  • Prüfe, ob der Token gültig ist: openclaw channels status --probe
  • Stelle sicher, dass der Absender genehmigt ist (Pairing oder allowFrom)
  • Prüfe die Gateway-Logs: openclaw logs --follow

Webhook empfängt keine Events:

  • Stelle sicher, dass die Webhook-URL HTTPS verwendet
  • Überprüfe, dass das Secret-Token 8-256 Zeichen lang ist
  • Bestätige, dass der Gateway-HTTP-Endpunkt unter dem konfigurierten Pfad erreichbar ist
  • Prüfe, dass getUpdates-Polling nicht läuft (sie schließen sich gegenseitig aus)

Konfigurationsreferenz (Zalo)

Vollständige Konfiguration: Configuration

Provider-Optionen:

  • channels.zalo.enabled: Kanal-Start aktivieren/deaktivieren.
  • channels.zalo.botToken: Bot-Token von der Zalo Bot Platform.
  • channels.zalo.tokenFile: Token aus einer regulären Datei lesen. Symlinks werden abgelehnt.
  • channels.zalo.dmPolicy: pairing | allowlist | open | disabled (Standard: pairing).
  • channels.zalo.allowFrom: DM-Allowlist (Benutzer-IDs). open erfordert "*". Der Assistent fragt nach numerischen IDs.
  • channels.zalo.groupPolicy: open | allowlist | disabled (Standard: allowlist).
  • channels.zalo.groupAllowFrom: Gruppen-Absender-Allowlist (Benutzer-IDs). Fällt auf allowFrom zurück, wenn nicht gesetzt.
  • channels.zalo.mediaMaxMb: Medien-Obergrenze ein-/ausgehend (MB, Standard 5).
  • channels.zalo.webhookUrl: Webhook-Modus aktivieren (HTTPS erforderlich).
  • channels.zalo.webhookSecret: Webhook-Secret (8-256 Zeichen).
  • channels.zalo.webhookPath: Webhook-Pfad auf dem Gateway-HTTP-Server.
  • channels.zalo.proxy: Proxy-URL für API-Anfragen.

Multi-Account-Optionen:

  • channels.zalo.accounts.<id>.botToken: Pro-Konto-Token.
  • channels.zalo.accounts.<id>.tokenFile: Reguläre Pro-Konto-Token-Datei. Symlinks werden abgelehnt.
  • channels.zalo.accounts.<id>.name: Anzeigename.
  • channels.zalo.accounts.<id>.enabled: Konto aktivieren/deaktivieren.
  • channels.zalo.accounts.<id>.dmPolicy: Pro-Konto-DM-Richtlinie.
  • channels.zalo.accounts.<id>.allowFrom: Pro-Konto-Allowlist.
  • channels.zalo.accounts.<id>.groupPolicy: Pro-Konto-Gruppenrichtlinie.
  • channels.zalo.accounts.<id>.groupAllowFrom: Pro-Konto-Gruppen-Absender-Allowlist.
  • channels.zalo.accounts.<id>.webhookUrl: Pro-Konto-Webhook-URL.
  • channels.zalo.accounts.<id>.webhookSecret: Pro-Konto-Webhook-Secret.
  • channels.zalo.accounts.<id>.webhookPath: Pro-Konto-Webhook-Pfad.
  • channels.zalo.accounts.<id>.proxy: Pro-Konto-Proxy-URL.
arrow_back
Zurück
Whatsapp
Weiter
Zalouser
arrow_forward