L'adapter contract des connecteurs : canaux et limites

Les canaux où vos clients se trouvent déjà

Un workspace AI est le plus utile dans le lieu où la conversation a déjà lieu. Pour beaucoup d'organisations, ce lieu n'est pas l'interface web que vous déployez ; ce sont les canaux de messagerie que les gens ouvrent sans y penser - les groupes WhatsApp, les chats Telegram, les serveurs Discord, les espaces Slack. Simmetric Chat traite ces canaux comme des surfaces de première classe d'une même base de connaissances : un connecteur lie un canal à un workspace et à une archive de documents, et chaque question arrivant sur ce canal reçoit une réponse du même pipeline de retrieval que le chat interne.

Le mot du titre - adapter contract - nomme la règle de conception qui rend cela sûr. Chaque plateforme parle un protocole différent avec des sémantiques d'identifiants différentes ; chacune tourne donc derrière un adapter dédié, et tout ce que l'adapter partage est un vocabulaire fixe de champs et de limites. Le résultat se lit comme une politique de sécurité : un connecteur par canal, un binding par connecteur, un corpus par binding.

Cet article parcourt le contract du côté de l'opérateur : ce que vous configurez à la création d'un connecteur, quelles surfaces changent à l'ère v0.28 (le volet de modification), comment les limites protègent le workspace du trafic externe, et ce qui se passe quand le corpus n'a aucune réponse citable.

Édition Enterprise uniquement : connectors_enabled est false dans la licence Community, le registre d'adapters y est vide et le panneau admin affiche l'invite de mise à niveau au lieu du formulaire de création. Faits : FACT-CENSUS.md F-CONN-1.

Ce que vous configurez à la création

Le formulaire de création vit dans Settings → Conversations → Connectors et demande deux classes de champs. Les champs de binding nomment l'intégration : un name identifiant l'instance, la platform (l'une de telegram, discord, slack, whatsapp), le token secret du canal et le workspace servi. Les champs comportementaux donnent forme à la conversation : le binding de l'archive de documents qui détermine le corpus, le message de bienvenue envoyé à qui ouvre une conversation, le message de repli avec sa fallbackLocale quand la recherche ne produit pas de sources citables, et les deux limites - rate limit et sessions journalières, où 0 signifie illimité.

Trois de ces champs sont immuables après création, et cette immuabilité n'est pas un détail d'implémentation - c'est le modèle de confiance. La plateforme et le token secret définissent qui peut parler au corpus ; le workspace définit ce qu'il peut atteindre. Si l'un des deux change, l'identité de l'intégration change, et le contract répond par un nouveau connecteur plutôt que par une mutation. Le schéma de la série v0.28 porte ces règles à la lettre : les messages de bienvenue et de repli plafonnent à 4000 caractères, la plateforme et le token sont create-only, et la PUT ne les touche jamais.

Les identifiants restent côté serveur par conception. L'application appelle les API du canal avec les identifiants que l'administrateur a saisis ; le token secret n'est jamais réaffiché dans l'interface après création, et le routage du connecteur vit dans votre propre infrastructure - le canal parle à votre serveur, votre serveur parle à sa propre base de connaissances.

La couche d'adapters

Chaque plateforme tourne derrière un adapter dédié, et l'enregistrement de chacun correspond à ce que la plateforme exige réellement :

• Telegram - un bot token de @BotFather, avec la prise en charge du polling comme du webhook (la carte porte les boutons dédiés au mode).
• Discord - un bot token du Developer Portal plus les intents de message ; l'adapter lit les canaux où le bot est autorisé.
• Slack - un bot token et le signing secret de l'application Slack ; les événements de message arrivent par le webhook configuré.
• WhatsApp - le token secret de la Business API du fournisseur ; l'adapter appelle l'API du fournisseur.

La couche d'adapters est l'endroit où meurent les différences entre plateformes. Vérification du webhook, périmètre des intents, boucles de polling, normalisation de la forme des messages - chacun vit derrière l'adapter de sa plateforme, et le reste du produit voit une forme unique d'enregistrement connecteur. Le registre d'adapters lui-même est gated : dans Community il est vide par construction, si bien qu'une instance Community échoue fermée avant qu'un trafic externe n'atteigne le workspace.

Modification : la surface mutable de v0.28.1

Avant v0.28.1, corriger un connecteur signifiait le supprimer et le recréer. Le changements de la série v0.28 ajoutent un volet de modification : le menu de débordement de la carte porte une entrée Edit qui ouvre un dialog pré-rempli sur exactement la surface mutable - via PUT /api/connectors/:id :

• Mutables - le nom, le binding de l'archive, les messages de bienvenue et de repli, la fallback locale, et les deux limites (vide = null ; 0 = illimité).
• Immuables - la plateforme, le bot token, le workspace.

La bascule isEnabled reste sur la carte (elle suspend le routage sans supprimer la configuration), et la mutation est auditée comme toute autre action admin : l'endpoint journalise l'événement chat_connector.updated, en équivalence avec le volet DELETE et son chat_connector.deleted. Le volet de modification compte dans l'histoire de l'opérateur pour une raison précise : relier un canal à une archive reconstruite, ou resserrer une limite après un incident, ne coûte plus l'identité du connecteur.

Le chemin de la réponse et le repli

Chaque question arrivant d'un canal passe par le même pipeline qu'un chat interne : recherche hybride sur l'archive liée, citation des sources, synthèse - puis la réponse citée repart sur le canal d'origine. Le binding de l'archive est le noyau silencieux du contract : c'est ce qui fonde une conversation externe.

Quand la recherche ne produit aucun élément valide citable, la réponse du contract est le message de repli - une réponse configurée dans la fallbackLocale configurée. Un canal externe ne reçoit jamais une génération non fondée quand le repli est en place ; le visiteur lit le message de repli au lieu d'une affirmation assurée sans rien derrière.

Les limites comme sas du workspace

Le rate limit et le daily session limit sont la protection du contract contre le trafic externe :

• 0 = illimité (la valeur sentinelle du routeur).
• N = le maximum par connecteur pour les requêtes, et pour les sessions par jour.

Ensemble avec isEnabled, ils laissent l'opérateur exposer la base de connaissances à un canal public en gardant le rayon d'action borné : un bot déréglé, un canal scrapé ou une audience inattendue consomme au plus la part configurée du workspace. Désactiver, resserrer ou relier - chacune est maintenant une modification unique (le volet v0.28.1), sans recréation.

Pour continuer

Le guide porte la procédure complète pour l'opérateur - le formulaire champ par champ, la table des adapters par plateforme, le comportement d'audit - sur /fr/docs/connectors :

• Connecteurs - le guide
• Faits de ce billet : lignes FACT-CENSUS.md F-CONN-1 (la barrière d'édition), F-CONN-2 (le volet de modification v0.28.1), F-LIC-1 (l'activation en collant la clé - sans toucher le serveur)

Provenance : paquets Simmetric Chat connector.schema.ts (formes des champs + limites), routes/connectors.ts (le routeur + le limiteur), CHANGELOG.md v0.28.1, license.ts (connectors_enabled) à l'état documentaire épinglé par le census v0.28.1 (SHA aca5b8ff).