Zalo (Bot API)

Status: experimentell. Nur Direktnachrichten; Gruppen laut Zalo-Docs in Kürze.

Plugin erforderlich

Zalo wird als Plugin ausgeliefert und ist nicht im Core-Install enthalten.

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

Schnelleinrichtung (Anfänger)

1. Zalo-Plugin installieren:
   • Aus Source-Checkout: openclaw plugins install ./extensions/zalo
   • Von npm (falls veröffentlicht): openclaw plugins install @openclaw/zalo
   • Oder Zalo im Onboarding wählen und Installationsaufforderung bestätigen
2. Token setzen:
   • Umgebung: ZALO_BOT_TOKEN=...
   • Oder Konfig: channels.zalo.botToken: "...".
3. Gateway neu starten (oder Onboarding abschließen).
4. DM-Zugang ist standardmäßig Pairing; Kopplungscode beim ersten Kontakt freigeben.

Minimale Konfiguration:

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

Ziele

Zalo ist eine auf Vietnam ausgerichtete Messaging-App; ihre Bot-API ermöglicht dem Gateway, einen Bot für 1:1-Gespräche zu betreiben. Geeignet für Support oder Benachrichtigungen mit deterministischem Routing zurück zu Zalo.

• Ein Zalo-Bot-API-Kanal, der dem Gateway gehört.
• Deterministisches Routing: Antworten gehen zurück zu Zalo; das Modell wählt nie Kanäle.
• DMs teilen die Hauptsitzung des Agenten.
• Gruppen werden noch nicht unterstützt (Zalo-Docs: „coming soon“).

Einrichtung (schneller Weg)

1) Bot-Token erstellen (Zalo Bot Platform)

1. Zu https://bot.zaloplatforms.com  gehen und anmelden.
2. Neuen Bot erstellen und Einstellungen konfigurieren.
3. Bot-Token kopieren (Format: 12345689:abc-xyz).

2) Token konfigurieren (Umgebung oder Konfiguration)

Beispiel:

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

Umgebungsoption: ZALO_BOT_TOKEN=... (gilt nur für das Standardkonto). Mehrkonten-Unterstützung: nutzen Sie channels.zalo.accounts mit Token pro Konto und optionalem name.

3. Gateway neu starten. Zalo startet, wenn ein Token aufgelöst ist (Umgebung oder Konfiguration).
4. DM-Zugang standardmäßig Pairing. Code freigeben, wenn der Bot erstmals kontaktiert wird.

Wie es funktioniert (Verhalten)

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

Limits

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

Zugriffskontrolle (DMs)

DM-Zugang

• Standard: channels.zalo.dmPolicy = "pairing". Unbekannte Absender erhalten einen Kopplungscode; Nachrichten werden ignoriert, bis sie freigegeben sind (Codes laufen nach 1 Stunde ab).
• Freigabe ü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 (kein Benutzernamen-Lookup verfügbar).

Long-Polling vs. Webhook

• Standard: Long-Polling (keine öffentliche URL erforderlich).

• Webhook-Modus: channels.zalo.webhookUrl und channels.zalo.webhookSecret setzen.

  • Das Webhook-Secret muss 8–256 Zeichen haben.
  • Webhook-URL muss HTTPS verwenden.
  • Zalo sendet Events mit Header X-Bot-Api-Secret-Token zur Verifizierung.
  • Gateway-HTTP bearbeitet Webhook-Anfragen unter channels.zalo.webhookPath (Standard: Pfad der Webhook-URL).

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

Unterstützte Nachrichtentypen

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

Funktionen

Zustellziele (CLI/Cron)

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

Fehlerbehebung

Bot antwortet nicht:

• Prüfen, ob der Token gültig ist: openclaw channels status --probe
• Sicherstellen, dass der Absender freigegeben ist (Pairing oder allowFrom)
• Gateway-Logs prüfen: openclaw logs --follow

Webhook empfängt keine Events:

• Sicherstellen, dass die Webhook-URL HTTPS nutzt
• Prüfen, ob das Secret-Token 8–256 Zeichen hat
• Bestätigen, dass der Gateway-HTTP-Endpunkt unter dem konfigurierten Pfad erreichbar ist
• Prüfen, dass getUpdates-Polling nicht läuft (sie schließen sich gegenseitig aus)

Konfigurationsreferenz (Zalo)

Vollständige Konfiguration: Konfiguration. Provider-Optionen:

• channels.zalo.enabled: Kanalstart aktivieren/deaktivieren.
• channels.zalo.botToken: Bot-Token von der Zalo Bot Platform.
• channels.zalo.tokenFile: Token aus Dateipfad lesen.
• channels.zalo.dmPolicy: pairing | allowlist | open | disabled (Standard: pairing).
• channels.zalo.allowFrom: DM-Zulassen-Liste (Benutzer-IDs). open erfordert "*". Der Assistent fragt nach numerischen IDs.
• channels.zalo.mediaMaxMb: eingehendes/ausgehendes Medien-Limit (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.

Mehrkonten-Optionen:

• channels.zalo.accounts.<id>.botToken: Token pro Konto.
• channels.zalo.accounts.<id>.tokenFile: Token-Datei pro Konto.
• channels.zalo.accounts.<id>.name: Anzeigename.
• channels.zalo.accounts.<id>.enabled: Konto aktivieren/deaktivieren.
• channels.zalo.accounts.<id>.dmPolicy: DM-Richtlinie pro Konto.
• channels.zalo.accounts.<id>.allowFrom: Zulassen-Liste pro Konto.
• channels.zalo.accounts.<id>.webhookUrl: Webhook-URL pro Konto.
• channels.zalo.accounts.<id>.webhookSecret: Webhook-Secret pro Konto.
• channels.zalo.accounts.<id>.webhookPath: Webhook-Pfad pro Konto.
• channels.zalo.accounts.<id>.proxy: Proxy-URL pro Konto.