Zalo

​

Paketle birlikte gelen plugin

• Kurulum: openclaw plugins install @openclaw/zalo
• Sabitlenmiş sürüm: openclaw plugins install @openclaw/zalo@2026.6.11
• Yerel bir çalışma kopyasından: openclaw plugins install ./path/to/local/zalo-plugin
• Ayrıntılar: Pluginler

​

Hızlı kurulum

1. https://bot.zaloplatforms.com adresinde bir bot token’ı oluşturun (oturum açın, bir bot oluşturun, ayarları yapılandırın). Token numeric_id:secret; Marketplace botlarında kullanılabilir çalışma zamanı token’ı botun karşılama mesajında görünebilir.
2. Token’ı yalnızca varsayılan hesap için ZALO_BOT_TOKEN=... ortam değişkeni olarak veya yapılandırmada ayarlayın.
3. Gateway’i yeniden başlatın.
4. İlk doğrudan mesaj iletişiminde eşleştirme kodunu onaylayın (varsayılan doğrudan mesaj politikası eşleştirmedir).

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

​

Nedir?

​

Nasıl çalışır?

• Gelen mesajlar, medya yer tutucularıyla birlikte paylaşılan kanal zarfına normalleştirilir.
• Yanıtlar her zaman aynı Zalo sohbetine geri yönlendirilir; alıntılı yanıt kullanılmaz (replyToMode sabit olarak kapalıdır).
• Varsayılan olarak uzun yoklama (getUpdates) kullanılır; webhook modu channels.zalo.webhookUrl aracılığıyla kullanılabilir.
• Gruplarda botu tetiklemek için @bahsetme gerekir; bu, kanal başına yapılandırılamaz.

​

Sınırlar

​

Erişim denetimi

​

Doğrudan mesajlar

• channels.zalo.dmPolicy: pairing (varsayılan) | allowlist | open | disabled.
• Eşleştirme: bilinmeyen gönderenler bir eşleştirme kodu alır; onaylanana kadar mesajlar yok sayılır. Kodların süresi 1 saat sonra dolar.
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
  • Ayrıntılar: Eşleştirme
• channels.zalo.allowFrom, sayısal Zalo kullanıcı kimliklerini kabul eder (kullanıcı adı araması yoktur). open, "*" gerektirir.

​

Gruplar

• channels.zalo.groupPolicy: open | allowlist | disabled.
• channels.zalo.groupAllowFrom, gruplarda hangi gönderen kimliklerinin botu tetikleyebileceğini sınırlar; ayarlanmadığında allowFrom kullanılır.
• Varsayılan çözümleme: channels.zalo yapılandırıldığında, ayarlanmamış bir groupPolicy değeri open olarak çözümlenir. channels.zalo tamamen eksik olduğunda çalışma zamanı güvenli biçimde allowlist değerine kapanır.
• Gerçek kullanımda bildirilen sınırlama: bazı Marketplace botu kurulumlarında bot hiçbir şekilde bir gruba eklenememiştir. Bununla karşılaşırsanız botunuzun Zalo Bot Platform ayarlarını doğrulayın; bu, OpenClaw politikası değil, platform kaynaklı bir kısıtlamadır.

​

Uzun yoklama ve webhook karşılaştırması

• Varsayılan: uzun yoklama (genel bir URL gerekmez).
• Webhook modu: channels.zalo.webhookUrl ve channels.zalo.webhookSecret değerlerini ayarlayın.
  • Webhook URL’si HTTPS kullanmalıdır.
  • Webhook gizli anahtarı 8-256 karakter olmalıdır.
  • Zalo, olayları sabit süreli karşılaştırmayla denetlenen bir X-Bot-Api-Secret-Token başlığıyla gönderir.
  • Gateway HTTP, webhook isteklerini channels.zalo.webhookPath konumunda işler (varsayılan olarak webhook URL’sinin yoludur).
  • İstekler Content-Type: application/json (veya bir +json medya türü) kullanmalıdır.
  • HTTP 200 yalnızca ham olay kalıcı olarak depolandıktan sonra döndürülür; depolama hataları HTTP 500 döndürür.
  • Zalo API belgelerine göre getUpdates yoklaması ile webhook birbirini dışlar.

​

Desteklenen mesaj türleri

• Metin: tam destek, 2000 karakterlik parçalara bölünür.
• Medya: gelen/giden, mediaMaxMb ile sınırlandırılır.
• Tepkiler, ileti dizileri, anketler, yerel komutlar: plugin tarafından desteklenmez.
• Akış: plugin blok akışı yeteneğini bildirir ancak Zalo’nun özel giden kuyruğu/metin birleştirme ayarları yoktur (diğer bazı bölgesel kanalların aksine); bu kullanım durumunuz için önemliyse ortamınızdaki güncel davranışı doğrulayın.

​

Yetenekler

​

Teslim hedefleri (CLI/cron)

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

​

Sorun giderme

• Token’ı denetleyin: openclaw channels status --probe
• Gönderenin onaylandığını doğrulayın (eşleştirme veya allowFrom)
• Gateway günlüklerini denetleyin: openclaw logs --follow

• Webhook URL’sinin HTTPS kullandığını doğrulayın
• Gizli anahtarın 8-256 karakter olduğunu doğrulayın
• Gateway HTTP uç noktasına yapılandırılmış yoldan erişilebildiğini doğrulayın
• getUpdates yoklamasının aynı anda çalışmadığını doğrulayın (birbirlerini dışlarlar)
• Ani bir istek yoğunluğu HTTP 429 döndürebilir (yol+IP başına 120 istek / 60s); bekleme süresini artırıp yeniden deneyin

​

Yapılandırma referansı

​

İlgili

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