Zalo (Bot API)

Status: experimenteel. DM’s worden ondersteund; groepsafhandeling is beschikbaar met expliciete groepsbeleidscontroles.

Plugin vereist

Zalo wordt als plugin geleverd en is niet gebundeld met de kerninstallatie.

  • Installeren via CLI: openclaw plugins install @openclaw/zalo
  • Of selecteer Zalo tijdens onboarding en bevestig de installatieprompt
  • Details: Plugins

Snelle installatie (beginner)

  1. Installeer de Zalo-plugin:
    • Vanuit een broncode-checkout: openclaw plugins install ./extensions/zalo
    • Vanuit npm (indien gepubliceerd): openclaw plugins install @openclaw/zalo
    • Of kies Zalo tijdens onboarding en bevestig de installatieprompt
  2. Stel het token in:
    • Omgevingsvariabele: ZALO_BOT_TOKEN=...
    • Of config: channels.zalo.botToken: "...".
  3. Herstart de gateway (of voltooi de onboarding).
  4. DM-toegang staat standaard op koppeling; keur de koppelingscode goed bij het eerste contact.

Minimale configuratie:

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

Wat het is

Zalo is een Vietnamese berichtenapp; de Bot API laat de Gateway een bot draaien voor 1:1-gesprekken. Het is geschikt voor ondersteuning of notificaties wanneer je deterministische routering terug naar Zalo wilt.

  • Een Zalo Bot API-kanaal beheerd door de Gateway.
  • Deterministische routering: antwoorden gaan terug naar Zalo; het model kiest nooit kanalen.
  • DM’s delen de hoofdsessie van de agent.
  • Groepen worden ondersteund met beleidscontroles (groupPolicy + groupAllowFrom) en gebruiken standaard fail-closed allowlist-gedrag.

Installatie (snel pad)

1) Maak een bottoken aan (Zalo Bot Platform)

  1. Ga naar https://bot.zaloplatforms.com en log in.
  2. Maak een nieuwe bot aan en configureer de instellingen.
  3. Kopieer het bottoken (formaat: 12345689:abc-xyz).

2) Configureer het token (omgevingsvariabele of config)

Voorbeeld:

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

Omgevingsvariabele: ZALO_BOT_TOKEN=... (werkt alleen voor het standaardaccount).

Multi-account-ondersteuning: gebruik channels.zalo.accounts met per-account tokens en optionele name.

  1. Herstart de gateway. Zalo start wanneer een token beschikbaar is (omgevingsvariabele of config).
  2. DM-toegang staat standaard op koppeling. Keur de code goed wanneer de bot voor het eerst wordt benaderd.

Hoe het werkt (gedrag)

  • Inkomende berichten worden genormaliseerd naar de gedeelde kanaalenvelop met mediaplaatshouders.
  • Antwoorden worden altijd teruggerouteerd naar dezelfde Zalo-chat.
  • Standaard long-polling; webhook-modus beschikbaar met channels.zalo.webhookUrl.

Limieten

  • Uitgaande tekst wordt opgesplitst bij 2000 tekens (Zalo API-limiet).
  • Mediadownloads/-uploads zijn begrensd door channels.zalo.mediaMaxMb (standaard 5).
  • Streaming is standaard geblokkeerd omdat de limiet van 2000 tekens streaming minder nuttig maakt.

Toegangscontrole (DM’s)

DM-toegang

  • Standaard: channels.zalo.dmPolicy = "pairing". Onbekende afzenders ontvangen een koppelingscode; berichten worden genegeerd totdat goedgekeurd (codes verlopen na 1 uur).
  • Goedkeuren via:
    • openclaw pairing list zalo
    • openclaw pairing approve zalo <CODE>
  • Koppeling is de standaard tokenuitwisseling. Details: Koppeling
  • channels.zalo.allowFrom accepteert numerieke gebruikers-ID’s (er is geen gebruikersnaamopzoeking beschikbaar).

Toegangscontrole (groepen)

  • channels.zalo.groupPolicy bepaalt de afhandeling van groepsinkomsten: open | allowlist | disabled.
  • Standaardgedrag is fail-closed: allowlist.
  • channels.zalo.groupAllowFrom beperkt welke afzender-ID’s de bot in groepen kunnen triggeren.
  • Als groupAllowFrom niet is ingesteld, valt Zalo terug op allowFrom voor afzendercontroles.
  • groupPolicy: "disabled" blokkeert alle groepsberichten.
  • groupPolicy: "open" staat elk groepslid toe (mention-gated).
  • Runtime-opmerking: als channels.zalo volledig ontbreekt, valt de runtime toch terug op groupPolicy="allowlist" voor de veiligheid.

Long-polling versus webhook

  • Standaard: long-polling (geen publieke URL vereist).
  • Webhook-modus: stel channels.zalo.webhookUrl en channels.zalo.webhookSecret in.
    • Het webhook-geheim moet 8-256 tekens zijn.
    • Webhook-URL moet HTTPS gebruiken.
    • Zalo stuurt events met de X-Bot-Api-Secret-Token-header voor verificatie.
    • Gateway HTTP verwerkt webhook-verzoeken op channels.zalo.webhookPath (standaard het webhook-URL-pad).
    • Verzoeken moeten Content-Type: application/json gebruiken (of +json-mediatypes).
    • Dubbele events (event_name + message_id) worden genegeerd gedurende een kort herhaalvenster.
    • Pieken in verkeer worden snelheidsbeperkt per pad/bron en kunnen HTTP 429 retourneren.

Opmerking: getUpdates (polling) en webhook zijn wederzijds exclusief volgens de Zalo API-documentatie.

Ondersteunde berichttypen

  • Tekstberichten: Volledige ondersteuning met opsplitsing bij 2000 tekens.
  • Afbeeldingsberichten: Download en verwerk inkomende afbeeldingen; verstuur afbeeldingen via sendPhoto.
  • Stickers: Gelogd maar niet volledig verwerkt (geen agentantwoord).
  • Niet-ondersteunde typen: Gelogd (bijv. berichten van beschermde gebruikers).

Mogelijkheden

FunctieStatus
Directe berichtenOndersteund
GroepenOndersteund met beleidscontroles (standaard allowlist)
Media (afbeeldingen)Ondersteund
ReactiesNiet ondersteund
ThreadsNiet ondersteund
PollsNiet ondersteund
Native commando’sNiet ondersteund
StreamingGeblokkeerd (2000-tekenlimiet)

Afleveringsdoelen (CLI/cron)

  • Gebruik een chat-ID als doel.
  • Voorbeeld: openclaw message send --channel zalo --target 123456789 --message "hi".

Probleemoplossing

Bot reageert niet:

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

Webhook ontvangt geen events:

  • Zorg ervoor dat de webhook-URL HTTPS gebruikt
  • Verifieer dat het geheime token 8-256 tekens is
  • Bevestig dat het gateway HTTP-eindpunt bereikbaar is op het geconfigureerde pad
  • Controleer of getUpdates-polling niet draait (ze zijn wederzijds exclusief)

Configuratiereferentie (Zalo)

Volledige configuratie: Configuratie

Provideropties:

  • channels.zalo.enabled: kanaal in-/uitschakelen bij opstart.
  • channels.zalo.botToken: bottoken van Zalo Bot Platform.
  • channels.zalo.tokenFile: lees token uit een regulier bestandspad. Symlinks worden geweigerd.
  • channels.zalo.dmPolicy: pairing | allowlist | open | disabled (standaard: pairing).
  • channels.zalo.allowFrom: DM-allowlist (gebruikers-ID’s). open vereist "*". De wizard vraagt om numerieke ID’s.
  • channels.zalo.groupPolicy: open | allowlist | disabled (standaard: allowlist).
  • channels.zalo.groupAllowFrom: groepsafzender-allowlist (gebruikers-ID’s). Valt terug op allowFrom wanneer niet ingesteld.
  • channels.zalo.mediaMaxMb: inkomende/uitgaande medialimiet (MB, standaard 5).
  • channels.zalo.webhookUrl: schakel webhook-modus in (HTTPS vereist).
  • channels.zalo.webhookSecret: webhook-geheim (8-256 tekens).
  • channels.zalo.webhookPath: webhook-pad op de gateway HTTP-server.
  • channels.zalo.proxy: proxy-URL voor API-verzoeken.

Multi-account-opties:

  • channels.zalo.accounts.<id>.botToken: per-account token.
  • channels.zalo.accounts.<id>.tokenFile: per-account regulier tokenbestand. Symlinks worden geweigerd.
  • channels.zalo.accounts.<id>.name: weergavenaam.
  • channels.zalo.accounts.<id>.enabled: account in-/uitschakelen.
  • channels.zalo.accounts.<id>.dmPolicy: per-account DM-beleid.
  • channels.zalo.accounts.<id>.allowFrom: per-account allowlist.
  • channels.zalo.accounts.<id>.groupPolicy: per-account groepsbeleid.
  • channels.zalo.accounts.<id>.groupAllowFrom: per-account groepsafzender-allowlist.
  • channels.zalo.accounts.<id>.webhookUrl: per-account webhook-URL.
  • channels.zalo.accounts.<id>.webhookSecret: per-account webhook-geheim.
  • channels.zalo.accounts.<id>.webhookPath: per-account webhook-pad.
  • channels.zalo.accounts.<id>.proxy: per-account proxy-URL.
arrow_back
Vorige
Whatsapp
Volgende
Zalouser
arrow_forward