Przejdź do głównej treści

​
Zalo (Bot API)

Status: eksperymentalny. Tylko wiadomości bezpośrednie; grupy wkrótce zgodnie z dokumentacją Zalo.

​
Wymagana wtyczka

Zalo jest dostarczane jako wtyczka i nie jest dołączone do instalacji rdzenia.
  • Instalacja przez CLI: openclaw plugins install @openclaw/zalo
  • Lub wybierz Zalo podczas onboardingu i potwierdź monit instalacji
  • Szczegóły: Plugins

​
Szybka konfiguracja (dla początkujących)

  1. Zainstaluj wtyczkę Zalo:
    • Z checkoutu źródeł: openclaw plugins install ./extensions/zalo
    • Z npm (jeśli opublikowana): openclaw plugins install @openclaw/zalo
    • Lub wybierz Zalo w onboardingu i potwierdź monit instalacji
  2. Ustaw token:
    • Wpis: ZALO_BOT_TOKEN=...
    • Lub konfiguracja: channels.zalo.botToken: "...".
  3. Zrestartuj gateway (lub zakończ onboarding).
  4. Dostęp do DM-ów domyślnie wymaga parowania; zatwierdź kod parowania przy pierwszym kontakcie.
Minimalna konfiguracja: 
{
  channels: {
    zalo: {
      enabled: true,
      botToken: "12345689:abc-xyz",
      dmPolicy: "pairing",
    },
  },
}

​
Czym to jest

Zalo to komunikator skoncentrowany na Wietnamie; jego Bot API pozwala Gateway uruchamiać bota do rozmów 1:1. To dobre rozwiązanie do wsparcia lub powiadomień, gdy potrzebne jest deterministyczne kierowanie odpowiedzi z powrotem do Zalo.
  • Kanał Zalo Bot API należący do Gateway.
  • Deterministyczne trasowanie: odpowiedzi wracają do Zalo; model nigdy nie wybiera kanałów.
  • DM-y współdzielą główną sesję agenta.
  • Grupy nie są jeszcze obsługiwane (dokumentacja Zalo wskazuje „coming soon”).

​
Konfiguracja (szybka ścieżka)

​
1. Utwórz token bota (Zalo Bot Platform)

  1. Przejdź do https://bot.zaloplatforms.com i zaloguj się.
  2. Utwórz nowego bota i skonfiguruj jego ustawienia.
  3. Skopiuj token bota (format: 12345689:abc-xyz).

​
2) Skonfiguruj token (env lub config)

Przykład: 
{
  channels: {
    zalo: {
      enabled: true,
      botToken: "12345689:abc-xyz",
      dmPolicy: "pairing",
    },
  },
}
Opcja env: ZALO_BOT_TOKEN=... (działa tylko dla konta domyślnego). Obsługa wielu kont: użyj channels.zalo.accounts z tokenami per konto oraz opcjonalnie name.
  1. Zrestartuj gateway. Zalo uruchamia się, gdy token zostanie rozpoznany (env lub config).
  2. Dostęp do DM-ów domyślnie wymaga parowania. Zatwierdź kod przy pierwszym kontakcie z botem.

​
Jak to działa (zachowanie)

  • Wiadomości przychodzące są normalizowane do wspólnej koperty kanału z placeholderami mediów.
  • Odpowiedzi zawsze wracają do tej samej rozmowy Zalo.
  • Domyślnie długie odpytywanie (long-polling); tryb webhook dostępny z channels.zalo.webhookUrl.

​
Limity

  • Tekst wychodzący jest dzielony na fragmenty po 2000 znaków (limit API Zalo).
  • Pobieranie/wysyłanie mediów jest ograniczone przez channels.zalo.mediaMaxMb (domyślnie 5).
  • Strumieniowanie jest domyślnie zablokowane, ponieważ limit 2000 znaków czyni je mniej użytecznym.

​
Kontrola dostępu (DM-y)

​
Dostęp do DM-ów

  • Domyślnie: channels.zalo.dmPolicy = "pairing". Nieznani nadawcy otrzymują kod parowania; wiadomości są ignorowane do czasu zatwierdzenia (kody wygasają po 1 godzinie).
  • Zatwierdzanie przez:
    • openclaw pairing list zalo
    • openclaw pairing approve zalo <CODE>
  • Parowanie jest domyślną wymianą tokenów. Szczegóły: Pairing
  • channels.zalo.allowFrom akceptuje numeryczne identyfikatory użytkowników (brak wyszukiwania po nazwie użytkownika).

​
Long-polling vs webhook

  • Domyślnie: long-polling (nie wymaga publicznego URL).
  • Tryb webhook: ustaw channels.zalo.webhookUrl i channels.zalo.webhookSecret.
    • Sekret webhooka musi mieć 8–256 znaków.
    • URL webhooka musi używać HTTPS.
    • Zalo wysyła zdarzenia z nagłówkiem X-Bot-Api-Secret-Token do weryfikacji.
    • HTTP Gateway obsługuje żądania webhooka pod channels.zalo.webhookPath (domyślnie ścieżka URL webhooka).
Uwaga: getUpdates (polling) i webhook są wzajemnie wykluczające się zgodnie z dokumentacją API Zalo.

​
Obsługiwane typy wiadomości

  • Wiadomości tekstowe: pełna obsługa z dzieleniem na 2000 znaków.
  • Wiadomości z obrazami: pobieranie i przetwarzanie obrazów przychodzących; wysyłanie obrazów przez sendPhoto.
  • Naklejki: rejestrowane, ale nie w pełni przetwarzane (brak odpowiedzi agenta).
  • Typy nieobsługiwane: rejestrowane (np. wiadomości od użytkowników chronionych).

​
Możliwości

FunkcjaStatus
Wiadomości bezpośrednie✅ Obsługiwane
Grupy❌ Wkrótce (wg dokumentacji Zalo)
Media (obrazy)✅ Obsługiwane
Reakcje❌ Nieobsługiwane
Wątki❌ Nieobsługiwane
Ankiety❌ Nieobsługiwane
Polecenia natywne❌ Nieobsługiwane
Strumieniowanie⚠️ Zablokowane (limit 2000 znaków)

​
Cele dostarczania (CLI/cron)

  • Użyj identyfikatora czatu jako celu.
  • Przykład: openclaw message send --channel zalo --target 123456789 --message "hi".

​
Rozwiązywanie problemów

Bot nie odpowiada:
  • Sprawdź, czy token jest prawidłowy: openclaw channels status --probe
  • Zweryfikuj, czy nadawca jest zatwierdzony (parowanie lub allowFrom)
  • Sprawdź logi gateway: openclaw logs --follow
Webhook nie odbiera zdarzeń:
  • Upewnij się, że URL webhooka używa HTTPS
  • Zweryfikuj, że sekret ma 8–256 znaków
  • Potwierdź, że punkt końcowy HTTP gateway jest osiągalny na skonfigurowanej ścieżce
  • Sprawdź, czy polling getUpdates nie jest uruchomiony (są wzajemnie wykluczające się)

​
Referencja konfiguracji (Zalo)

Pełna konfiguracja: Configuration Opcje dostawcy:
  • channels.zalo.enabled: włącz/wyłącz uruchamianie kanału.
  • channels.zalo.botToken: token bota z Zalo Bot Platform.
  • channels.zalo.tokenFile: odczyt tokena z pliku.
  • channels.zalo.dmPolicy: pairing | allowlist | open | disabled (domyślnie: parowanie).
  • channels.zalo.allowFrom: lista dozwolonych DM-ów (identyfikatory użytkowników). open wymaga "*". Kreator poprosi o identyfikatory numeryczne.
  • channels.zalo.mediaMaxMb: limit mediów przychodzących/wychodzących (MB, domyślnie 5).
  • channels.zalo.webhookUrl: włącz tryb webhook (wymagany HTTPS).
  • channels.zalo.webhookSecret: sekret webhooka (8–256 znaków).
  • channels.zalo.webhookPath: ścieżka webhooka na serwerze HTTP gateway.
  • channels.zalo.proxy: URL proxy dla żądań API.
Opcje wielu kont:
  • channels.zalo.accounts.<id>.botToken: token per konto.
  • channels.zalo.accounts.<id>.tokenFile: plik tokena per konto.
  • channels.zalo.accounts.<id>.name: nazwa wyświetlana.
  • channels.zalo.accounts.<id>.enabled: włącz/wyłącz konto.
  • channels.zalo.accounts.<id>.dmPolicy: polityka DM per konto.
  • channels.zalo.accounts.<id>.allowFrom: lista dozwolonych 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: ścieżka webhooka per konto.
  • channels.zalo.accounts.<id>.proxy: URL proxy per konto.