Zalo (Bot API)

Status: eksperymentalny. DM sa obslugiwane; obsluga grup jest dostepna z jawnymi kontrolami polityki grupowej.

Wymagany plugin

Zalo jest dostarczany jako plugin i nie jest dolaczony do instalacji podstawowej.

• Instalacja przez CLI: openclaw plugins install @openclaw/zalo
• Lub wybierz Zalo podczas onboardingu i potwierdz monit instalacji
• Szczegoly: Pluginy

Szybka konfiguracja (dla poczatkujacych)

1. Zainstaluj plugin Zalo:
   • Z checkoutu zrodlowego: openclaw plugins install ./extensions/zalo
   • Z npm (jesli opublikowany): openclaw plugins install @openclaw/zalo
   • Lub wybierz Zalo w onboardingu i potwierdz monit instalacji
2. Ustaw token:
   • Zmienna: ZALO_BOT_TOKEN=...
   • Lub konfiguracja: channels.zalo.botToken: "...".
3. Zrestartuj gateway (lub zakoncz onboarding).
4. Dostep DM domyslnie wymaga parowania; zatwierdz kod parowania przy pierwszym kontakcie.

Minimalna konfiguracja:

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

Czym jest

Zalo to komunikator skoncentrowany na Wietnamie; jego Bot API pozwala Gateway uruchomic bota do rozmow 1:1. Jest dobrze dopasowany do wsparcia lub powiadomien, gdy chcesz deterministycznego routingu z powrotem do Zalo.

• Kanal Zalo Bot API nalezacy do Gateway.
• Deterministyczny routing: odpowiedzi wracaja do Zalo; model nigdy nie wybiera kanalow.
• DM wspoldziela glowna sesje agenta.
• Grupy sa obslugiwane z kontrolami polityki (groupPolicy + groupAllowFrom) i domyslnie stosuja zamknieta polityke listy dozwolonych.

Konfiguracja (szybka sciezka)

1) Utworz token bota (Zalo Bot Platform)

1. Wejdz na https://bot.zaloplatforms.com i zaloguj sie.
2. Utworz nowego bota i skonfiguruj jego ustawienia.
3. Skopiuj token bota (format: 12345689:abc-xyz).

2) Skonfiguruj token (zmienna lub konfiguracja)

Przyklad:

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

Opcja zmiennej: ZALO_BOT_TOKEN=... (dziala tylko dla domyslnego konta).

Obsluga wielu kont: uzyj channels.zalo.accounts z tokenami per konto i opcjonalnym name.

3. Zrestartuj gateway. Zalo uruchomi sie gdy token zostanie znaleziony (zmienna lub konfiguracja).
4. Dostep DM domyslnie wymaga parowania. Zatwierdz kod przy pierwszym kontakcie z botem.

Jak dziala (zachowanie)

• Wiadomosci przychodzace sa normalizowane do wspolnej koperty kanalu z zastepczymi mediami.
• Odpowiedzi sa zawsze routowane z powrotem do tego samego czatu Zalo.
• Domyslnie long-polling; tryb webhooka dostepny z channels.zalo.webhookUrl.

Limity

• Tekst wychodzacy jest dzielony na kawalki po 2000 znakow (limit API Zalo).
• Pobieranie/wysylanie mediow jest ograniczone przez channels.zalo.mediaMaxMb (domyslnie 5).
• Strumieniowanie jest domyslnie blokowane ze wzgledu na limit 2000 znakow, ktory czyni strumieniowanie mniej przydatnym.

Kontrola dostepu (DM)

Dostep DM

• Domyslnie: channels.zalo.dmPolicy = "pairing". Nieznani nadawcy otrzymuja kod parowania; wiadomosci sa ignorowane do momentu zatwierdzenia (kody wygasaja po 1 godzinie).
• Zatwierdzanie przez:
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
• Parowanie to domyslna wymiana tokenow. Szczegoly: Parowanie
• channels.zalo.allowFrom akceptuje numeryczne ID uzytkownikow (wyszukiwanie nazw niedostepne).

Kontrola dostepu (grupy)

• channels.zalo.groupPolicy kontroluje obsluge przychodzacych wiadomosci grupowych: open | allowlist | disabled.
• Domyslne zachowanie jest zamkniete: allowlist.
• channels.zalo.groupAllowFrom ogranicza, ktore ID nadawcow moga wyzwalac bota w grupach.
• Jesli groupAllowFrom nie jest ustawione, Zalo stosuje zastepczym allowFrom do sprawdzen nadawcow.
• groupPolicy: "disabled" blokuje wszystkie wiadomosci grupowe.
• groupPolicy: "open" zezwala kazdemu czlonkowi grupy (bramkowane wzmiankami).
• Uwaga runtime: jesli channels.zalo calkowicie brakuje, runtime nadal stosuje zastepczym groupPolicy="allowlist" dla bezpieczenstwa.

Long-polling vs webhook

• Domyslnie: long-polling (nie wymaga publicznego URL).
• Tryb webhooka: ustaw channels.zalo.webhookUrl i channels.zalo.webhookSecret.
  • Sekret webhooka musi miec 8-256 znakow.
  • URL webhooka musi uzywac HTTPS.
  • Zalo wysyla zdarzenia z naglowkiem X-Bot-Api-Secret-Token do weryfikacji.
  • HTTP Gateway obsluguje zadania webhooka pod channels.zalo.webhookPath (domyslnie sciezka URL webhooka).
  • Zadania musza uzywac Content-Type: application/json (lub typow mediow +json).
  • Zduplikowane zdarzenia (event_name + message_id) sa ignorowane w krotkim oknie powtorki.
  • Ruch impulsowy jest limitowany szybkoscia per sciezka/zrodlo i moze zwrocic HTTP 429.

Uwaga: getUpdates (polling) i webhook wykluczaja sie wzajemnie wg dokumentacji API Zalo.

Obslugiwane typy wiadomosci

• Wiadomosci tekstowe: pelna obsluga z dzieleniem na kawalki po 2000 znakow.
• Wiadomosci ze zdjeciami: pobieranie i przetwarzanie przychodzacych zdjec; wysylanie zdjec przez sendPhoto.
• Naklejki: rejestrowane, ale nie w pelni przetwarzane (brak odpowiedzi agenta).
• Nieobslugiwane typy: rejestrowane (np. wiadomosci od chronionych uzytkownikow).

Mozliwosci

Cele dostarczania (CLI/cron)

• Uzyj ID czatu jako celu.
• Przyklad: openclaw message send --channel zalo --target 123456789 --message "hi".

Rozwiazywanie problemow

Bot nie odpowiada:

• Sprawdz, czy token jest prawidlowy: openclaw channels status --probe
• Zweryfikuj, czy nadawca jest zatwierdzony (parowanie lub allowFrom)
• Sprawdz logi gateway: openclaw logs --follow

Webhook nie odbiera zdarzen:

• Upewnij sie, ze URL webhooka uzywa HTTPS
• Zweryfikuj, ze token sekretu ma 8-256 znakow
• Potwierdz, ze endpoint HTTP gateway jest osiagalny pod skonfigurowana sciezka
• Sprawdz, czy polling getUpdates nie jest uruchomiony (sa wzajemnie wykluczone)

Referencja konfiguracji (Zalo)

Pelna konfiguracja: Konfiguracja

Opcje dostawcy:

• channels.zalo.enabled: wlaczenie/wylaczenie startu kanalu.
• channels.zalo.botToken: token bota z Zalo Bot Platform.
• channels.zalo.tokenFile: odczyt tokenu ze zwyklego pliku. Dowiazania symboliczne sa odrzucane.
• channels.zalo.dmPolicy: pairing | allowlist | open | disabled (domyslnie: pairing).
• channels.zalo.allowFrom: lista dozwolonych DM (ID uzytkownikow). open wymaga "*". Kreator zapyta o numeryczne ID.
• channels.zalo.groupPolicy: open | allowlist | disabled (domyslnie: allowlist).
• channels.zalo.groupAllowFrom: lista dozwolonych nadawcow grupowych (ID uzytkownikow). Stosuje zastepczym allowFrom gdy nie ustawione.
• channels.zalo.mediaMaxMb: limit mediow przychodzacych/wychodzacych (MB, domyslnie 5).
• channels.zalo.webhookUrl: wlaczenie trybu webhooka (wymagany HTTPS).
• channels.zalo.webhookSecret: sekret webhooka (8-256 znakow).
• channels.zalo.webhookPath: sciezka webhooka na serwerze HTTP gateway.
• channels.zalo.proxy: URL proxy dla zadan API.

Opcje wielu kont:

• channels.zalo.accounts.<id>.botToken: token per konto.
• channels.zalo.accounts.<id>.tokenFile: plik tokenu per konto. Dowiazania symboliczne sa odrzucane.
• channels.zalo.accounts.<id>.name: nazwa wyswietlana.
• channels.zalo.accounts.<id>.enabled: wlaczenie/wylaczenie konta.
• channels.zalo.accounts.<id>.dmPolicy: polityka DM per konto.
• channels.zalo.accounts.<id>.allowFrom: lista dozwolonych per konto.
• channels.zalo.accounts.<id>.groupPolicy: polityka grupowa per konto.
• channels.zalo.accounts.<id>.groupAllowFrom: lista dozwolonych nadawcow grupowych per konto.
• channels.zalo.accounts.<id>.webhookUrl: URL webhooka per konto.
• channels.zalo.accounts.<id>.webhookSecret: sekret webhooka per konto.
• channels.zalo.accounts.<id>.webhookPath: sciezka webhooka per konto.
• channels.zalo.accounts.<id>.proxy: URL proxy per konto.