Guide de configuration des adaptateurs multi-canaux OpenFang

20 min de lecture

OpenFang prend en charge plus de 40 adaptateurs de canaux. Cet article détaille la configuration complète de six adaptateurs courants : CLI, WhatsApp Business API, Telegram Bot, Discord, Slack Socket Mode et le widget Web Chat. Il inclut des solutions pour l'exécution multi-canaux simultanée, le partage de contexte, le renforcement de la sécurité et la surveillance de l'état.

Guide de configuration des adaptateurs multi-canaux OpenFang : rendez votre agent omniprésent

Slug: openfang-channel-setup-guide Catégorie: usage-guides (Guides d'utilisation) Mots-clés cibles: configuration canaux OpenFang, adaptateurs OpenFang, OpenFang WhatsApp Telegram Intention de recherche: Informationnelle (l'utilisateur souhaite connecter son agent à différentes plateformes) Nombre de mots cible: ~1800 mots Langue: fr

Qu'est-ce qu'un adaptateur de canal ?

Un adaptateur de canal (Channel Adapter) est le pont entre OpenFang et les plateformes externes. Chaque adaptateur est responsable de la conversion des messages de la plateforme externe vers un format unifié compréhensible par OpenFang, et de la conversion des réponses de l'agent vers le format natif de la plateforme.

La philosophie de conception d'OpenFang est : "Écrivez la logique de votre agent une seule fois, exécutez-la sur plus de 40 plateformes". Vous n'avez pas besoin de réécrire votre agent pour chaque plateforme ; il suffit de configurer l'adaptateur de canal correspondant.

Actuellement, OpenFang prend en charge plus de 40 adaptateurs de canaux, couvrant la messagerie instantanée, les réseaux sociaux, les outils de collaboration, les e-mails et les API personnalisées.

Concepts fondamentaux des adaptateurs de canaux

Tous les adaptateurs de canaux partagent les principes de conception suivants :

  • Format de message unifié : Quel que soit le canal d'origine, les messages sont convertis au format standard OpenFang Message.
  • Bac à sable indépendant : Chaque adaptateur de canal s'exécute dans un bac à sable isolé ; une défaillance sur un canal n'affecte pas les autres.
  • Chargement à chaud (Hot-loading) : Aucun redémarrage de l'agent n'est nécessaire après l'ajout ou la modification d'une configuration de canal.
  • Limitation de débit (Rate limiting) : Protection intégrée pour éviter de déclencher les limites de l'API des plateformes.

Configuration des adaptateurs de canaux courants

Adaptateur CLI

La CLI est l'adaptateur le plus basique, idéal pour le développement, le débogage et l'utilisation locale :

toml
[channels.cli]enabled = truehistory_size = 1000              # Nombre de messages conservés dans l'historiqueprompt_style = "rich"            # plain / rich / minimal

L'adaptateur CLI est prêt à l'emploi sans configuration supplémentaire. Il prend en charge la saisie multiligne, la complétion de commandes et la coloration syntaxique.

Adaptateur WhatsApp

WhatsApp est l'un des outils de messagerie les plus utilisés au monde. Grâce à l'API WhatsApp Business, votre agent peut interagir directement avec les utilisateurs sur WhatsApp :

toml
[channels.whatsapp]enabled = trueapi_version = "v18.0"phone_number_id = "${WA_PHONE_NUMBER_ID}"access_token = "${WA_ACCESS_TOKEN}"verify_token = "${WA_VERIFY_TOKEN}"[channels.whatsapp.features]media_support = true             # Prise en charge des images/fichiersreply_buttons = true             # Prise en charge des boutons interactifsmax_message_length = 4096typing_indicator = true          # Afficher "En train d'écrire..."

Étapes de configuration :

  1. Créez une application WhatsApp sur Meta for Developers.
  2. Obtenez le Phone Number ID et l'Access Token.
  3. Configurez l'URL du Webhook (votre adresse de serveur OpenFang + /webhook/whatsapp).
  4. Saisissez ces informations dans la configuration d'OpenFang.

Adaptateur Telegram

Telegram est l'une des plateformes de communication les plus populaires au sein de la communauté technique. Sa configuration est simple et son API conviviale :

toml
[channels.telegram]enabled = truebot_token = "${TELEGRAM_BOT_TOKEN}"allowed_users = []               # Laisser vide = tous les utilisateurs peuvent accéderadmin_users = ["@your_username"][channels.telegram.features]inline_queries = true            # Prise en charge des requêtes en lignemarkdown_support = truefile_upload = truemax_file_size_mb = 50

Étapes de configuration :

  1. Discutez avec @BotFather sur Telegram pour créer un bot.
  2. Obtenez le Bot Token.
  3. Saisissez le jeton dans le fichier de configuration.

Adaptateur Discord

L'adaptateur Discord prend en charge les serveurs (Guilds) et les messages privés :

toml
[channels.discord]enabled = truebot_token = "${DISCORD_BOT_TOKEN}"application_id = "${DISCORD_APP_ID}"[channels.discord.guilds]server_ids = ["1234567890"]      # IDs des serveurs autorisés[channels.discord.features]slash_commands = true            # Prise en charge des commandes slashthread_support = true            # Prise en charge des fils de discussionembed_messages = true            # Messages enrichis (embeds)

Adaptateur Slack

Idéal pour les scénarios de collaboration en entreprise :

toml
[channels.slack]enabled = truebot_token = "${SLACK_BOT_TOKEN}"signing_secret = "${SLACK_SIGNING_SECRET}"app_token = "${SLACK_APP_TOKEN}"[channels.slack.features]socket_mode = true               # Utiliser le Socket Mode (recommandé, aucune URL publique nécessaire)thread_replies = truereaction_feedback = true

Slack recommande l'utilisation du Socket Mode, qui ne nécessite pas de configurer une URL de Webhook accessible publiquement, ce qui est idéal pour les déploiements sur réseau interne.

Adaptateur Web Chat

Intégrez une fenêtre de discussion OpenFang sur votre site web :

toml
[channels.webchat]enabled = trueport = 3000cors_origins = ["https://your-site.com"][channels.webchat.ui]theme = "auto"                   # light / dark / autologo_url = "/assets/agent-logo.png"welcome_message = "Bonjour ! Je suis l'agent OpenFang, comment puis-je vous aider ?"placeholder = "Posez votre question..."

Une fois configuré, ajoutez ceci à votre page web :

html
<script src="https://your-server:3000/widget.js"></script><script>OpenFangWidget.init({ position: 'bottom-right' })</script>

Exécution multi-canaux simultanée

L'architecture d'OpenFang prend naturellement en charge le multi-canal parallèle. Le cœur de l'agent maintient un état de session unifié, et tous les canaux partagent le contexte :

toml
# Activer plusieurs canaux simultanément[channels]cli.enabled = truewhatsapp.enabled = truetelegram.enabled = truediscord.enabled = truewebchat.enabled = true[channels.routing]strategy = "context_aware"       # round_robin / context_aware / prioritypreserve_context = true          # Conserver le contexte pour un utilisateur sur plusieurs canaux

La stratégie de routage context_aware signifie que si un utilisateur commence une conversation sur WhatsApp puis passe à Telegram, l'agent chargera automatiquement le contexte précédent.

Configuration de la sécurité des canaux

Le multi-canal implique une surface d'attaque plus large. OpenFang offre un contrôle de sécurité granulaire par canal :

toml
[channels.security]per_user_rate_limit = 30         # Max 30 messages par utilisateur et par minuteper_channel_rate_limit = 100     # Max 100 messages par canal et par minuterequire_auth = ["discord", "slack"]public_channels = ["webchat"]authenticated_channels = ["whatsapp", "telegram", "discord", "slack"][channels.security.content_filter]block_urls = falseblock_attachments = falsemax_prompt_length = 4000

Conseils de sécurité clés :

  • Activez une limitation de débit stricte pour les canaux accessibles publiquement (Web Chat).
  • En environnement de production, tous les canaux autres que la CLI devraient exiger une authentification utilisateur.
  • Auditez régulièrement les journaux d'accès aux canaux.

Surveillance de l'état des canaux

bash
# Voir l'état de tous les canauxopenfang channels list# Exemple de sortie :# Channel        Status    Messages/24h   Errors   Latency# cli            ✅ active       0           0         -# telegram       ✅ active     156          2       120ms# whatsapp       ✅ active      89          0       250ms# discord        ⚠️ degraded    43          5       500ms# webchat        ✅ active      12          0        45ms# Redémarrer un canal spécifiqueopenfang channels restart discord# Voir les journaux détaillés d'un canalopenfang channels logs telegram --level debug

Foire aux questions

Faut-il redémarrer l'agent pour ajouter un nouveau canal ?
Non. OpenFang prend en charge le chargement à chaud des configurations de canaux :

``bash
openfang channels reload
``

L'historique des conversations est-il partagé entre les différents canaux ?
Par défaut, oui. L'historique des conversations d'un même utilisateur est partagé entre tous les canaux ; changer de canal ne fait pas perdre le contexte. Si vous avez besoin d'isoler les canaux, vous pouvez configurer preserve_context = false.
L'adaptateur WhatsApp nécessite-t-il un compte WhatsApp Business ?
Oui. L'adaptateur WhatsApp utilise l'API WhatsApp Business Platform et nécessite un compte Business vérifié. Les comptes WhatsApp personnels ne prennent pas en charge l'accès par API.
Comment ajouter un adaptateur de canal personnalisé ?
OpenFang fournit un SDK de canal. Implémentez le trait ChannelAdapter pour créer un adaptateur personnalisé :

``rust
use openfang::channels::{ChannelAdapter, Message};

struct MyCustomChannel;
impl ChannelAdapter for MyCustomChannel {
async fn receive(&self) -> Vec<Message> { /* ... */ }
async fn send(&self, msg: Message) -> Result<()> { /* ... */ }
}
``

Prochaines étapes

  • Guide de création de flux de travail automatisés OpenFang : Orchestrez votre agent multi-canal en processus automatisés.
  • Meilleures pratiques de sécurité OpenFang : Sécurisez vos déploiements d'agents multi-canaux.