Zalo

​

Plugin intégré

• Installation : openclaw plugins install @openclaw/zalo
• Version épinglée : openclaw plugins install @openclaw/zalo@2026.6.11
• Depuis une copie de travail locale : openclaw plugins install ./path/to/local/zalo-plugin
• Détails : Plugins

​

Configuration rapide

1. Créez un jeton de bot sur https://bot.zaloplatforms.com (connectez-vous, créez un bot et configurez ses paramètres). Le jeton suit le format numeric_id:secret ; pour les bots Marketplace, le jeton utilisable à l’exécution peut apparaître dans le message de bienvenue du bot.
2. Définissez le jeton, soit dans la variable d’environnement ZALO_BOT_TOKEN=... (compte par défaut uniquement), soit dans la configuration.
3. Redémarrez le Gateway.
4. Approuvez le code d’association lors du premier contact par message direct (la politique par défaut des messages directs est l’association).

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

​

Présentation

​

Fonctionnement

• Les messages entrants sont normalisés dans l’enveloppe de canal commune avec des espaces réservés pour les médias.
• Les réponses sont toujours renvoyées vers la même discussion Zalo ; la réponse avec citation n’est pas utilisée (replyToMode est désactivé de manière fixe).
• L’interrogation longue (getUpdates) est utilisée par défaut ; le mode Webhook est disponible via channels.zalo.webhookUrl.
• Dans les groupes, une @mention est nécessaire pour déclencher le bot ; ce comportement n’est pas configurable par canal.

​

Limites

​

Contrôle d’accès

​

Messages directs

• channels.zalo.dmPolicy : pairing (par défaut) | allowlist | open | disabled.
• Association : les expéditeurs inconnus reçoivent un code d’association ; les messages sont ignorés jusqu’à son approbation. Les codes expirent au bout d’une heure.
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
  • Détails : Association
• channels.zalo.allowFrom accepte les identifiants utilisateur Zalo numériques (aucune recherche par nom d’utilisateur). open nécessite "*".

​

Groupes

• channels.zalo.groupPolicy : open | allowlist | disabled.
• channels.zalo.groupAllowFrom limite les identifiants d’expéditeurs autorisés à déclencher le bot dans les groupes ; si cette valeur n’est pas définie, allowFrom est utilisée.
• Résolution par défaut : lorsque channels.zalo est configuré, une valeur groupPolicy non définie est résolue en open. Lorsque channels.zalo est entièrement absent, l’exécution adopte par sécurité allowlist.
• Limitation signalée en conditions réelles : dans certaines configurations de bots Marketplace, il était impossible d’ajouter le bot à un groupe. Si vous rencontrez ce problème, vérifiez les paramètres Zalo Bot Platform de votre bot ; il s’agit d’une contrainte de la plateforme et non d’une politique OpenClaw.

​

Interrogation longue ou Webhook

• Par défaut : interrogation longue (aucune URL publique requise).
• Mode Webhook : définissez channels.zalo.webhookUrl et channels.zalo.webhookSecret.
  • L’URL du Webhook doit utiliser HTTPS.
  • Le secret du Webhook doit comporter entre 8 et 256 caractères.
  • Zalo envoie les événements avec un en-tête X-Bot-Api-Secret-Token, vérifié au moyen d’une comparaison en temps constant.
  • Le serveur HTTP du Gateway traite les requêtes Webhook à l’emplacement channels.zalo.webhookPath (par défaut, le chemin de l’URL du Webhook).
  • Les requêtes doivent utiliser Content-Type: application/json (ou un type de média +json).
  • Selon la documentation de l’API Zalo, l’interrogation getUpdates et le Webhook sont mutuellement exclusifs.

​

Types de messages pris en charge

• Texte : prise en charge complète, avec découpage en segments de 2 000 caractères.
• Médias : entrants et sortants, limités par mediaMaxMb.
• Réactions, fils de discussion, sondages et commandes natives : non pris en charge par le Plugin.
• Diffusion en continu : le Plugin déclare la prise en charge de la diffusion par blocs, mais Zalo ne possède aucun paramètre dédié au réglage de la file d’attente sortante ou de la fusion du texte, contrairement à certains autres canaux régionaux ; si cela est important pour votre cas d’utilisation, vérifiez le comportement actuel dans votre environnement.

​

Fonctionnalités

​

Destinations de livraison (CLI/Cron)

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

​

Dépannage

• Vérifiez le jeton : openclaw channels status --probe
• Vérifiez que l’expéditeur est approuvé (association ou allowFrom)
• Consultez les journaux du Gateway : openclaw logs --follow

• Vérifiez que l’URL du Webhook utilise HTTPS
• Vérifiez que le secret comporte entre 8 et 256 caractères
• Vérifiez que le point de terminaison HTTP du Gateway est accessible sur le chemin configuré
• Vérifiez que l’interrogation getUpdates ne s’exécute pas également (les deux modes sont mutuellement exclusifs)
• Une rafale de requêtes peut entraîner une réponse HTTP 429 (120 requêtes par période de 60 s, par chemin et IP) ; attendez avant de réessayer

​

Référence de configuration

​

Pages associées

• Vue d’ensemble des canaux - tous les canaux pris en charge
• Association - authentification des messages directs et processus d’association
• Groupes - comportement des discussions de groupe et déclenchement par mention
• Routage des canaux - routage des sessions pour les messages
• Sécurité - modèle d’accès et renforcement de la sécurité