Zalo (Bot API)

Statut : experimental. Les DMs sont pris en charge ; la gestion des groupes est disponible avec des controles de politique de groupe explicites.

Plugin requis

Zalo est fourni comme plugin et n’est pas inclus dans l’installation de base.

• Installation via CLI : openclaw plugins install @openclaw/zalo
• Ou selectionnez Zalo pendant l’onboarding et confirmez l’invite d’installation
• Details : Plugins

Configuration rapide (debutant)

1. Installez le plugin Zalo :
   • Depuis un checkout source : openclaw plugins install ./extensions/zalo
   • Depuis npm (si publie) : openclaw plugins install @openclaw/zalo
   • Ou choisissez Zalo dans l’onboarding et confirmez l’invite d’installation
2. Definissez le jeton :
   • Env : ZALO_BOT_TOKEN=...
   • Ou config : channels.zalo.botToken: "...".
3. Redemarrez la gateway (ou terminez l’onboarding).
4. L’acces DM est en mode appairage par defaut ; approuvez le code d’appairage au premier contact.

Configuration minimale :

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

Description

Zalo est une application de messagerie centree sur le Vietnam ; son Bot API permet a la Gateway d’executer un bot pour les conversations 1:1. C’est un bon choix pour le support ou les notifications ou vous souhaitez un routage deterministe vers Zalo.

• Un canal Zalo Bot API gere par la Gateway.
• Routage deterministe : les reponses retournent a Zalo ; le modele ne choisit jamais les canaux.
• Les DMs partagent la session principale de l’agent.
• Les groupes sont pris en charge avec des controles de politique (groupPolicy + groupAllowFrom) et utilisent par defaut un comportement de liste d’autorisation ferme.

Configuration (chemin rapide)

1) Creer un jeton de bot (Zalo Bot Platform)

1. Allez sur https://bot.zaloplatforms.com et connectez-vous.
2. Creez un nouveau bot et configurez ses parametres.
3. Copiez le jeton du bot (format : 12345689:abc-xyz).

2) Configurer le jeton (env ou config)

Exemple :

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

Option env : ZALO_BOT_TOKEN=... (fonctionne uniquement pour le compte par defaut).

Support multi-comptes : utilisez channels.zalo.accounts avec des jetons par compte et un name optionnel.

3. Redemarrez la gateway. Zalo demarre quand un jeton est resolu (env ou config).
4. L’acces DM est par defaut en mode appairage. Approuvez le code quand le bot est contacte pour la premiere fois.

Fonctionnement (comportement)

• Les messages entrants sont normalises dans l’enveloppe de canal partagee avec des espaces reserves pour les medias.
• Les reponses retournent toujours a la meme conversation Zalo.
• Long-polling par defaut ; mode webhook disponible avec channels.zalo.webhookUrl.

Limites

• Le texte sortant est decoupe a 2000 caracteres (limite API Zalo).
• Les telechargements/envois de medias sont limites par channels.zalo.mediaMaxMb (par defaut 5).
• Le streaming est bloque par defaut car la limite de 2000 caracteres rend le streaming moins utile.

Controle d’acces (DMs)

Acces DM

• Par defaut : channels.zalo.dmPolicy = "pairing". Les expediteurs inconnus recoivent un code d’appairage ; les messages sont ignores jusqu’a approbation (les codes expirent apres 1 heure).
• Approbation via :
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
• L’appairage est l’echange de jetons par defaut. Details : Appairage
• channels.zalo.allowFrom accepte les IDs utilisateur numeriques (pas de recherche par nom d’utilisateur disponible).

Controle d’acces (Groupes)

• channels.zalo.groupPolicy controle le traitement des groupes entrants : open | allowlist | disabled.
• Le comportement par defaut est ferme : allowlist.
• channels.zalo.groupAllowFrom restreint quels IDs d’expediteur peuvent declencher le bot dans les groupes.
• Si groupAllowFrom n’est pas defini, Zalo se replie sur allowFrom pour les verifications d’expediteur.
• groupPolicy: "disabled" bloque tous les messages de groupe.
• groupPolicy: "open" autorise tout membre de groupe (filtre par mention).
• Remarque d’execution : si channels.zalo est completement absent, l’execution se replie quand meme sur groupPolicy="allowlist" pour la securite.

Long-polling vs webhook

• Par defaut : long-polling (pas d’URL publique requise).
• Mode webhook : definissez channels.zalo.webhookUrl et channels.zalo.webhookSecret.
  • Le secret du webhook doit faire 8-256 caracteres.
  • L’URL du webhook doit utiliser HTTPS.
  • Zalo envoie les evenements avec l’en-tete X-Bot-Api-Secret-Token pour la verification.
  • La gateway HTTP traite les requetes webhook a channels.zalo.webhookPath (par defaut le chemin de l’URL du webhook).
  • Les requetes doivent utiliser Content-Type: application/json (ou des types media +json).
  • Les evenements dupliques (event_name + message_id) sont ignores pendant une courte fenetre de relecture.
  • Le trafic en rafale est limite en debit par chemin/source et peut retourner HTTP 429.

Remarque : getUpdates (polling) et webhook sont mutuellement exclusifs selon la documentation de l’API Zalo.

Types de messages pris en charge

• Messages texte : Support complet avec decoupe a 2000 caracteres.
• Messages image : Telechargement et traitement des images entrantes ; envoi d’images via sendPhoto.
• Stickers : Enregistres mais pas entierement traites (pas de reponse de l’agent).
• Types non pris en charge : Enregistres (ex : messages d’utilisateurs proteges).

Fonctionnalites

Cibles de livraison (CLI/cron)

• Utilisez un ID de chat comme cible.
• Exemple : openclaw message send --channel zalo --target 123456789 --message "hi".

Depannage

Le bot ne repond pas :

• Verifiez que le jeton est valide : openclaw channels status --probe
• Verifiez que l’expediteur est approuve (appairage ou allowFrom)
• Verifiez les logs de la gateway : openclaw logs --follow

Le webhook ne recoit pas d’evenements :

• Assurez-vous que l’URL du webhook utilise HTTPS
• Verifiez que le jeton secret fait 8-256 caracteres
• Confirmez que l’endpoint HTTP de la gateway est accessible sur le chemin configure
• Verifiez que le polling getUpdates n’est pas en cours (ils sont mutuellement exclusifs)

Reference de configuration (Zalo)

Configuration complete : Configuration

Options du fournisseur :

• channels.zalo.enabled : activer/desactiver le demarrage du canal.
• channels.zalo.botToken : jeton de bot de la Zalo Bot Platform.
• channels.zalo.tokenFile : lire le jeton depuis un chemin de fichier regulier. Les liens symboliques sont rejetes.
• channels.zalo.dmPolicy : pairing | allowlist | open | disabled (par defaut : pairing).
• channels.zalo.allowFrom : liste d’autorisation DM (IDs utilisateur). open necessite "*". L’assistant demandera des IDs numeriques.
• channels.zalo.groupPolicy : open | allowlist | disabled (par defaut : allowlist).
• channels.zalo.groupAllowFrom : liste d’autorisation d’expediteurs de groupe (IDs utilisateur). Se replie sur allowFrom quand non defini.
• channels.zalo.mediaMaxMb : limite de media entrant/sortant (Mo, par defaut 5).
• channels.zalo.webhookUrl : activer le mode webhook (HTTPS requis).
• channels.zalo.webhookSecret : secret du webhook (8-256 caracteres).
• channels.zalo.webhookPath : chemin du webhook sur le serveur HTTP de la gateway.
• channels.zalo.proxy : URL du proxy pour les requetes API.

Options multi-comptes :

• channels.zalo.accounts.<id>.botToken : jeton par compte.
• channels.zalo.accounts.<id>.tokenFile : fichier de jeton regulier par compte. Les liens symboliques sont rejetes.
• channels.zalo.accounts.<id>.name : nom d’affichage.
• channels.zalo.accounts.<id>.enabled : activer/desactiver le compte.
• channels.zalo.accounts.<id>.dmPolicy : politique DM par compte.
• channels.zalo.accounts.<id>.allowFrom : liste d’autorisation par compte.
• channels.zalo.accounts.<id>.groupPolicy : politique de groupe par compte.
• channels.zalo.accounts.<id>.groupAllowFrom : liste d’autorisation d’expediteurs de groupe par compte.
• channels.zalo.accounts.<id>.webhookUrl : URL du webhook par compte.
• channels.zalo.accounts.<id>.webhookSecret : secret du webhook par compte.
• channels.zalo.accounts.<id>.webhookPath : chemin du webhook par compte.
• channels.zalo.accounts.<id>.proxy : URL du proxy par compte.