Zalo

​

Gebundelde Plugin

• 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).

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

​

Wat het is

​

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

• 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)

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

​

Probleemoplossing

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

• 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

​

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