​

Zalo (Bot API)

​

Paketlenmiş plugin

• CLI ile yükleyin: openclaw plugins install @openclaw/zalo
• Veya bir kaynak checkout’tan: openclaw plugins install ./path/to/local/zalo-plugin
• Ayrıntılar: Plugins

​

Hızlı kurulum (başlangıç)

1. Zalo plugin’inin kullanılabilir olduğundan emin olun.
   • Güncel paketlenmiş OpenClaw sürümleri bunu zaten içerir.
   • Eski/özel kurulumlar bunu yukarıdaki komutlarla el ile ekleyebilir.
2. Token’ı ayarlayın:
   • Ortam değişkeni: ZALO_BOT_TOKEN=...
   • Veya yapılandırma: channels.zalo.accounts.default.botToken: "...".
3. Gateway’i yeniden başlatın (veya kurulumu tamamlayın).
4. DM erişimi varsayılan olarak eşleştirmedir; ilk temasta eşleştirme kodunu onaylayın.

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

​

Nedir

• Gateway’e ait bir Zalo Bot API kanalı.
• Belirlenimli yönlendirme: yanıtlar Zalo’ya geri gider; model kanalları seçmez.
• DM’ler ajanın ana oturumunu paylaşır.
• Aşağıdaki Yetenekler bölümü mevcut Marketplace bot desteğini gösterir.

​

Kurulum (hızlı yol)

​

1) Bir bot token’ı oluşturun (Zalo Bot Platform)

1. https://bot.zaloplatforms.com adresine gidin ve oturum açın.
2. Yeni bir bot oluşturun ve ayarlarını yapılandırın.
3. Tam bot token’ını kopyalayın (genellikle numeric_id:secret). Marketplace botları için kullanılabilir çalışma zamanı token’ı, oluşturma işleminden sonra botun hoş geldin mesajında görünebilir.

​

2) Token’ı yapılandırın (ortam değişkeni veya yapılandırma)

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

3. Gateway’i yeniden başlatın. Zalo, bir token çözümlendiğinde (ortam değişkeni veya yapılandırma) başlar.
4. DM erişimi varsayılan olarak eşleştirmedir. Bot ile ilk kez iletişime geçildiğinde kodu onaylayın.

​

Nasıl çalışır (davranış)

• Gelen mesajlar, medya yer tutucularıyla paylaşılan kanal zarfına normalize edilir.
• Yanıtlar her zaman aynı Zalo sohbetine geri yönlendirilir.
• Varsayılan olarak long-polling kullanılır; channels.zalo.webhookUrl ile webhook modu kullanılabilir.

​

Sınırlar

• Giden metin 2000 karaktere bölünür (Zalo API sınırı).
• Medya indirme/yükleme işlemleri channels.zalo.mediaMaxMb ile sınırlandırılır (varsayılan 5).
• 2000 karakter sınırı akışı daha az yararlı hale getirdiği için akış varsayılan olarak engellenir.

​

Erişim denetimi (DM’ler)

​

DM erişimi

• Varsayılan: channels.zalo.dmPolicy = "pairing". Bilinmeyen göndericiler bir eşleştirme kodu alır; onaylanana kadar mesajlar yok sayılır (kodların süresi 1 saat sonra dolar).
• Şununla onaylayın:
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
• Eşleştirme varsayılan token değişimidir. Ayrıntılar: Eşleştirme
• channels.zalo.allowFrom sayısal kullanıcı kimliklerini kabul eder (kullanıcı adı araması yoktur).

​

Erişim denetimi (Gruplar)

• channels.zalo.groupPolicy, gruplardaki gelen işlemeyi denetler: open | allowlist | disabled.
• channels.zalo.groupAllowFrom, gruplarda hangi gönderici kimliklerinin botu tetikleyebileceğini sınırlar.
• groupAllowFrom ayarlanmamışsa Zalo, gönderici denetimleri için allowFrom değerine geri döner.
• Çalışma zamanı notu: channels.zalo tamamen eksikse çalışma zamanı güvenlik için yine groupPolicy="allowlist" değerine geri döner.

• groupPolicy: "disabled" — tüm grup mesajlarını engeller.
• groupPolicy: "open" — herhangi bir grup üyesine izin verir (bahsetme geçidiyle).
• groupPolicy: "allowlist" — başarısızlık durumunda kapalı varsayılan; yalnızca izin verilen göndericiler kabul edilir.

​

Long-polling ve webhook karşılaştırması

• Varsayılan: long-polling (genel bir URL gerekmez).
• Webhook modu: channels.zalo.webhookUrl ve channels.zalo.webhookSecret ayarlayın.
  • Webhook secret 8-256 karakter olmalıdır.
  • Webhook URL’si HTTPS kullanmalıdır.
  • Zalo, doğrulama için olayları X-Bot-Api-Secret-Token başlığı ile gönderir.
  • Gateway HTTP, webhook isteklerini channels.zalo.webhookPath üzerinde işler (varsayılan olarak webhook URL yolu).
  • İstekler Content-Type: application/json (veya +json medya türleri) kullanmalıdır.
  • Yinelenen olaylar (event_name + message_id) kısa bir tekrar penceresi boyunca yok sayılır.
  • Ani trafik artışı yol/kaynak başına hız sınırına tabidir ve HTTP 429 döndürebilir.

​

Desteklenen mesaj türleri

• Metin mesajları: 2000 karaktere bölme ile tam destek.
• Metin içindeki düz URL’ler: Normal metin girdisi gibi davranır.
• Bağlantı önizlemeleri / zengin bağlantı kartları: Marketplace bot durumuna bakmak için bkz. Yetenekler; güvenilir şekilde yanıt tetiklemediler.
• Görüntü mesajları: Marketplace bot durumuna bakmak için bkz. Yetenekler; gelen görüntü işleme güvenilir değildi (son yanıt olmadan yazıyor göstergesi).
• Sticker’lar: Marketplace bot durumuna bakmak için bkz. Yetenekler.
• Sesli notlar / ses dosyaları / video / genel dosya ekleri: Marketplace bot durumuna bakmak için bkz. Yetenekler.
• Desteklenmeyen türler: Günlüğe kaydedilir (örneğin, korumalı kullanıcılardan gelen mesajlar).

​

Yetenekler

​

Teslimat hedefleri (CLI/cron)

• Hedef olarak bir sohbet kimliği kullanın.
• Örnek: openclaw message send --channel zalo --target 123456789 --message "hi".

​

Sorun giderme

• Token’ın geçerli olduğunu kontrol edin: openclaw channels status --probe
• Göndericinin onaylandığını doğrulayın (eşleştirme veya allowFrom)
• Gateway günlüklerini kontrol edin: openclaw logs --follow

• Webhook URL’sinin HTTPS kullandığından emin olun
• Secret token’ın 8-256 karakter olduğunu doğrulayın
• Gateway HTTP uç noktasının yapılandırılmış yolda erişilebilir olduğunu doğrulayın
• getUpdates polling işleminin çalışmadığını kontrol edin (birbirini dışlar)

​

Yapılandırma başvurusu (Zalo)

• channels.zalo.enabled: kanal başlatmayı etkinleştirir/devre dışı bırakır.
• channels.zalo.botToken: Zalo Bot Platform’dan bot token’ı.
• channels.zalo.tokenFile: token’ı normal bir dosya yolundan okur. Symlink’ler reddedilir.
• channels.zalo.dmPolicy: pairing | allowlist | open | disabled (varsayılan: pairing).
• channels.zalo.allowFrom: DM izin listesi (kullanıcı kimlikleri). open, "*" gerektirir. Sihirbaz sayısal kimlikleri sorar.
• channels.zalo.groupPolicy: open | allowlist | disabled (varsayılan: allowlist). Yapılandırmada bulunur; mevcut Marketplace bot davranışı için bkz. Yetenekler ve Erişim denetimi (Gruplar).
• channels.zalo.groupAllowFrom: grup gönderici izin listesi (kullanıcı kimlikleri). Ayarlanmadığında allowFrom değerine geri döner.
• channels.zalo.mediaMaxMb: gelen/giden medya sınırı (MB, varsayılan 5).
• channels.zalo.webhookUrl: webhook modunu etkinleştirir (HTTPS gereklidir).
• channels.zalo.webhookSecret: webhook secret’ı (8-256 karakter).
• channels.zalo.webhookPath: gateway HTTP sunucusundaki webhook yolu.
• channels.zalo.proxy: API istekleri için proxy URL’si.

• channels.zalo.accounts.<id>.botToken: hesap başına token.
• channels.zalo.accounts.<id>.tokenFile: hesap başına normal token dosyası. Symlink’ler reddedilir.
• channels.zalo.accounts.<id>.name: görünen ad.
• channels.zalo.accounts.<id>.enabled: hesabı etkinleştirir/devre dışı bırakır.
• channels.zalo.accounts.<id>.dmPolicy: hesap başına DM ilkesi.
• channels.zalo.accounts.<id>.allowFrom: hesap başına izin listesi.
• channels.zalo.accounts.<id>.groupPolicy: hesap başına grup ilkesi. Yapılandırmada bulunur; mevcut Marketplace bot davranışı için bkz. Yetenekler ve Erişim denetimi (Gruplar).
• channels.zalo.accounts.<id>.groupAllowFrom: hesap başına grup gönderici izin listesi.
• channels.zalo.accounts.<id>.webhookUrl: hesap başına webhook URL’si.
• channels.zalo.accounts.<id>.webhookSecret: hesap başına webhook secret’ı.
• channels.zalo.accounts.<id>.webhookPath: hesap başına webhook yolu.
• channels.zalo.accounts.<id>.proxy: hesap başına proxy URL’si.

​

İlgili

• Kanallara Genel Bakış — desteklenen tüm kanallar
• Eşleştirme — DM kimlik doğrulaması ve eşleştirme akışı
• Gruplar — grup sohbeti davranışı ve bahsetme geçidi
• Kanal Yönlendirme — mesajlar için oturum yönlendirme
• Güvenlik — erişim modeli ve sağlamlaştırma