Zalo (Bot API)

Status: experimentell. Nur Direktnachrichten; Gruppen kommen laut Zalo-Dokumentation bald.

Plugin erforderlich

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

• Installation per 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 Source-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:
   • Env: ZALO_BOT_TOKEN=...
   • Oder config: channels.zalo.botToken: "...".
3. Starte den Gateway neu (oder schließe das Onboarding ab).
4. DM-Zugriff ist standardmäßig auf Pairing eingestellt; gib den Pairing-Code beim ersten Kontakt frei.

Minimale Konfiguration:

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

Was ist Zalo

Zalo ist eine auf Vietnam fokussierte Messaging-App; die Bot API ermöglicht es dem Gateway, einen Bot für 1:1-Konversationen zu betreiben. Ideal für Support oder Benachrichtigungen, bei denen du deterministisches Routing zurück zu Zalo brauchst.

• Ein Zalo Bot API Channel, der vom Gateway verwaltet wird.
• Deterministisches Routing: Antworten gehen zurück zu Zalo; das Modell wählt nie Channels aus.
• DMs teilen die Haupt-Session des Agents.
• Gruppen werden noch nicht unterstützt (Zalo-Dokumentation sagt “coming soon”).

Einrichtung (schneller Weg)

1) Bot-Token erstellen (Zalo Bot Platform)

1. Geh 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 (env oder config)

Beispiel:

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

Env-Option: ZALO_BOT_TOKEN=... (funktioniert nur für den Standard-Account).

Multi-Account-Unterstützung: Nutze channels.zalo.accounts mit Account-spezifischen Tokens und optionalem name.

3. Starte den Gateway neu. Zalo startet, sobald ein Token aufgelöst wird (env oder config).
4. DM-Zugriff ist standardmäßig auf Pairing eingestellt. Gib den Code frei, wenn der Bot zum ersten Mal kontaktiert wird.

Wie es funktioniert (Verhalten)

• Eingehende Nachrichten werden in den gemeinsamen Channel-Envelope mit Media-Platzhaltern normalisiert.
• Antworten werden immer zurück zum selben Zalo-Chat geroutet.
• Standardmäßig Long-Polling; Webhook-Modus verfügbar mit channels.zalo.webhookUrl.

Limits

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

Zugriffskontrolle (DMs)

DM-Zugriff

• Standard: channels.zalo.dmPolicy = "pairing". Unbekannte Absender erhalten einen Pairing-Code; Nachrichten werden ignoriert, bis sie freigegeben sind (Codes laufen nach 1 Stunde ab).
• Freigabe via:
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
• Pairing ist der Standard-Token-Austausch. Details: Pairing
• channels.zalo.allowFrom akzeptiert numerische User-IDs (kein Username-Lookup verfügbar).

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 X-Bot-Api-Secret-Token Header zur Verifizierung.
  • Gateway HTTP verarbeitet Webhook-Requests unter channels.zalo.webhookPath (Standard: der Webhook-URL-Pfad).

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

Unterstützte Nachrichtentypen

• Textnachrichten: Volle Unterstützung mit 2000-Zeichen-Chunking.
• Bildnachrichten: Download und Verarbeitung eingehender Bilder; Bilder senden via sendPhoto.
• Sticker: Werden geloggt, aber nicht vollständig verarbeitet (keine Agent-Antwort).
• Nicht unterstützte Typen: Werden geloggt (z. B. Nachrichten von geschützten Nutzern).

Funktionen

Delivery Targets (CLI/Cron)

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

Troubleshooting

Bot antwortet nicht:

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

Webhook empfängt keine Events:

• Stelle sicher, dass die Webhook-URL HTTPS verwendet
• Verifiziere, dass das Secret-Token 8-256 Zeichen lang ist
• Bestätige, dass der Gateway HTTP-Endpoint 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: Channel-Start 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-Allowlist (User-IDs). open erfordert "*". Der Wizard fragt nach numerischen IDs.
• channels.zalo.mediaMaxMb: Inbound/Outbound Media-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-Requests.

Multi-Account-Optionen:

• channels.zalo.accounts.<id>.botToken: Account-spezifischer Token.
• channels.zalo.accounts.<id>.tokenFile: Account-spezifische Token-Datei.
• channels.zalo.accounts.<id>.name: Anzeigename.
• channels.zalo.accounts.<id>.enabled: Account aktivieren/deaktivieren.
• channels.zalo.accounts.<id>.dmPolicy: Account-spezifische DM-Policy.
• channels.zalo.accounts.<id>.allowFrom: Account-spezifische Allowlist.
• channels.zalo.accounts.<id>.webhookUrl: Account-spezifische Webhook-URL.
• channels.zalo.accounts.<id>.webhookSecret: Account-spezifisches Webhook-Secret.
• channels.zalo.accounts.<id>.webhookPath: Account-spezifischer Webhook-Pfad.
• channels.zalo.accounts.<id>.proxy: Account-spezifische Proxy-URL.