Zalo

Status: experimenteel. Directe berichten en groepschats zijn beide geïmplementeerd; de onderstaande tabel Mogelijkheden geeft geverifieerd gedrag weer voor Zalo Bot Creator-/Marketplace-bots.

Gebundelde Plugin

Zalo wordt als gebundelde Plugin meegeleverd in de huidige OpenClaw-releases, dus voor verpakte builds is geen afzonderlijke installatie nodig.

Installeer bij een oudere build of een aangepaste installatie zonder Zalo het npm-pakket rechtstreeks:

• Installeren: openclaw plugins install @openclaw/zalo
• Vastgezette versie: openclaw plugins install @openclaw/zalo@2026.6.11
• Vanuit een lokale checkout: openclaw plugins install ./path/to/local/zalo-plugin
• Details: Plugins

Snelle configuratie

1. Maak een bottoken aan op https://bot.zaloplatforms.com (meld je aan, maak een bot en configureer de instellingen). Het token is numeric_id:secret; voor Marketplace-bots kan het bruikbare runtimetoken in het welkomstbericht van de bot staan.
2. Stel het token in via de omgevingsvariabele ZALO_BOT_TOKEN=... (alleen voor het standaardaccount) of in de configuratie.
3. Start de Gateway opnieuw.
4. Keur bij het eerste contact via een direct bericht de koppelingscode goed (het standaardbeleid voor directe berichten is koppeling).

Minimale configuratie:

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

Meerdere accounts: voeg meer vermeldingen toe onder channels.zalo.accounts.<id>, elk met een eigen botToken/name. channels.zalo.botToken (vlak, zonder accounts) is een verouderde verkorte notatie voor één account; geef voor nieuwe configuraties de voorkeur aan accounts.<id>.*.

Wat het is

Zalo is een berichtenapp die zich op Vietnam richt. Met de Bot API kan de Gateway een bot uitvoeren voor zowel 1:1-gesprekken als groepschats, met deterministische routering terug naar Zalo (het model kiest nooit kanalen).

Deze pagina behandelt Zalo Bot Creator-/Marketplace-bots. Zalo Official Account-bots (OA) vormen een ander productoppervlak en kunnen zich anders gedragen; deze pagina behandelt ze niet.

Hoe het werkt

• Inkomende berichten worden met mediaplaatshouders genormaliseerd naar de gedeelde kanaalenvelop.
• Antwoorden worden altijd teruggeleid naar dezelfde Zalo-chat; geciteerd antwoorden wordt niet gebruikt (replyToMode staat permanent uit).
• Standaard wordt long-polling (getUpdates) gebruikt; de webhookmodus is beschikbaar via channels.zalo.webhookUrl.
• In groepen is een @vermelding vereist om de bot te activeren; dit is niet per kanaal configureerbaar.

Limieten

Toegangsbeheer

Directe berichten

• channels.zalo.dmPolicy: pairing (standaard) | allowlist | open | disabled.
• Koppeling: onbekende afzenders krijgen een koppelingscode; berichten worden genegeerd totdat deze is goedgekeurd. Codes verlopen na 1 uur.
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
  • Details: Koppeling
• channels.zalo.allowFrom accepteert numerieke Zalo-gebruikers-ID's (geen zoekactie op gebruikersnaam). Voor open is "*" vereist.

Groepen

Groepschats worden door de Plugin ondersteund (chatTypes: ["direct", "group"]) en worden beperkt door een vermelding en het groepsbeleid:

• channels.zalo.groupPolicy: open | allowlist | disabled.
• channels.zalo.groupAllowFrom beperkt welke afzender-ID's de bot in groepen kunnen activeren; wanneer dit niet is ingesteld, wordt teruggevallen op allowFrom.
• Standaardresolutie: wanneer channels.zalo is geconfigureerd, wordt een niet-ingestelde groupPolicy opgelost als open. Wanneer channels.zalo volledig ontbreekt, weigert de runtime standaard toegang via allowlist.
• Gemelde praktijkbeperking: bij sommige Marketplace-botconfiguraties kon de bot helemaal niet aan een groep worden toegevoegd. Als dit gebeurt, controleer dan de Zalo Bot Platform-instellingen van je bot; dit is een beperking van het platform, geen beleid van OpenClaw.

Long-polling versus webhook

• Standaard: long-polling (geen openbare URL vereist).
• Webhookmodus: stel channels.zalo.webhookUrl en channels.zalo.webhookSecret in.
  • De webhook-URL moet HTTPS gebruiken.
  • Het webhookgeheim moet 8-256 tekens lang zijn.
  • Zalo verzendt gebeurtenissen met een X-Bot-Api-Secret-Token-header, die wordt gecontroleerd met een vergelijking met constante uitvoeringstijd.
  • Gateway HTTP verwerkt webhookaanvragen op channels.zalo.webhookPath (standaard het pad van de webhook-URL).
  • Aanvragen moeten Content-Type: application/json (of een +json-mediatype) gebruiken.
  • HTTP 200 wordt pas geretourneerd nadat de onbewerkte gebeurtenis duurzaam is opgeslagen; opslagfouten retourneren HTTP 500.
  • Volgens de documentatie van de Zalo API sluiten getUpdates-polling en een webhook elkaar wederzijds uit.

Ondersteunde berichttypen

• Tekst: volledig ondersteund, opgesplitst in segmenten van 2000 tekens.
• Media: inkomend/uitgaand, beperkt door mediaMaxMb.
• Reacties, threads, peilingen en native opdrachten: niet ondersteund door de Plugin.
• Streaming: de Plugin declareert ondersteuning voor blokstreaming, maar Zalo heeft geen specifieke instelopties voor een uitgaande wachtrij of het samenvoegen van tekst (in tegenstelling tot sommige andere regionale kanalen); verifieer het huidige gedrag in je omgeving als dit voor jouw gebruikssituatie van belang is.

Mogelijkheden

Afleveringsdoelen (CLI/cron)

Gebruik een chat-ID als doel:

openclaw message send --channel zalo --target 123456789 --message "hi"

Probleemoplossing

Bot reageert niet:

• Controleer het token: openclaw channels status --probe
• Controleer of de afzender is goedgekeurd (koppeling of allowFrom)
• Controleer de Gateway-logboeken: openclaw logs --follow

Webhook ontvangt geen gebeurtenissen:

• Controleer of de webhook-URL HTTPS gebruikt
• Controleer of het geheim 8-256 tekens lang is
• Controleer of het HTTP-eindpunt van de Gateway bereikbaar is via het geconfigureerde pad
• Controleer of getUpdates-polling niet ook actief is (ze sluiten elkaar wederzijds uit)
• Een piek in het aantal aanvragen kan HTTP 429 opleveren (120 aanvragen / 60s per pad+IP); wacht langer tussen pogingen en probeer het opnieuw

Configuratiereferentie

Volledige configuratie: Configuratie

channels.zalo.botToken, channels.zalo.dmPolicy en andere vlakke sleutels op het hoogste niveau vormen de verouderde verkorte notatie voor één account voor de bovenstaande velden; beide vormen worden ondersteund.

Omgevingsoptie: ZALO_BOT_TOKEN=... levert alleen het token van het standaardaccount op.

Gerelateerd

• Overzicht van kanalen - alle ondersteunde kanalen
• Koppeling - authenticatie voor directe berichten en koppelingsflow
• Groepen - gedrag van groepschats en vereiste vermeldingen
• Kanaalroutering - sessieroutering voor berichten
• Beveiliging - toegangsmodel en beveiliging aanscherpen