L'adapter contract dei connettori: canali e limiti

I canali dove i vostri clienti si trovano già

Un workspace AI è più utile nel luogo dove la conversazione avviene già. Per molte organizzazioni quel luogo non è l'interfaccia web che distribuite; sono i canali di messaggistica che le persone aprono senza pensarci - i gruppi WhatsApp, le chat Telegram, i server Discord, gli spazi Slack. Simmetric Chat tratta quei canali come superfici di prima classe della stessa knowledge base: un connettore lega un canale a un workspace e a un archivio documentale, e ogni domanda che arriva su quel canale riceve risposta dalla stessa pipeline di retrieval del chat interno.

La parola nel titolo - adapter contract - nomina la regola di progettazione che rende tutto ciò sicuro. Ogni piattaforma parla un protocollo diverso con semantiche di credenziali diverse, quindi ognuna gira dietro un adapter dedicato; tutto ciò che l'adapter condivide è un vocabolario fisso di campi e limiti. Il risultato si legge come una policy di sicurezza: un connettore per canale, un binding per connettore, un corpus per binding.

Questo articolo percorre il contract dal lato dell'operatore: cosa configurate alla creazione di un connettore, quali superfici cambiano nell'era v0.28 (il ramo di modifica), come i limiti proteggono il workspace dal traffico esterno, e cosa accade quando il corpus non ha una risposta citabile.

Solo edizione Enterprise: connectors_enabled è false nella licenza Community, l'adapter registry è vuota in quella sede e il pannello admin mostra l'upgrade prompt invece del form di creazione. Fatti da FACT-CENSUS.md F-CONN-1.

Cosa configurate alla creazione

Il form di creazione vive in Settings → Conversations → Connectors e chiede due classi di campi. I campi di binding nominano l'integrazione: un name per identificare l'istanza, la platform (una tra telegram, discord, slack, whatsapp), il token segreto del canale e il workspace che il connettore serve. I campi comportamentali danno forma alla conversazione: il binding dell'archivio documentale che determina il corpus, il messaggio di benvenuto che il canale invia a chi apre la conversazione, il messaggio di fallback con il suo fallbackLocale usato quando la ricerca non produce fonti citabili, e i due limiti - rate limit e sessioni giornaliere, dove 0 significa illimitato.

Tre di quei campi sono immutabili dopo la creazione, e l'immutabilità non è un dettaglio implementativo - è il modello di fiducia. La piattaforma e il token segreto definiscono chi può parlare col corpus; il workspace definisce cosa può raggiungere. Se uno dei due cambia, l'identità dell'integrazione cambia, e il contract risponde con un nuovo connettore invece che con una mutazione. Lo schema della serie v0.28 porta quelle regole alla lettera: i messaggi di benvenuto e fallback arrivano a 4000 caratteri di tetto, piattaforma e token sono create-only, e la PUT non li tocca mai.

Le credenziali restano lato server per progettazione. L'app chiama le API del canale con le credenziali che l'amministratore ha inserito; il token segreto non viene mai riflesso in interfaccia dopo la creazione, e il routing del connettore vive nella vostra infrastruttura - il canale parla col vostro server, il vostro server parla con la propria knowledge base.

Il layer degli adapter

Ogni piattaforma gira con un adapter dedicato, e la registrazione di ciascuno rispecchia ciò che la piattaforma richiede davvero:

• Telegram - un bot token da @BotFather, con supporto sia del polling sia del webhook (la scheda porta i pulsanti dedicati alla modalità).
• Discord - un bot token dal Developer Portal più gli intenti messaggio; l'adapter legge i canali per cui il bot è autorizzato.
• Slack - un bot token e il signing secret dell'app Slack; gli eventi messaggio arrivano attraverso il webhook configurato.
• WhatsApp - il token segreto della Business API del provider; l'adapter chiama l'API del provider.

Il layer degli adapter è dove le differenze per piattaforma muoiono. Verifica del webhook, scoping degli intenti, loop di polling, normalizzazione della forma dei messaggi - ognuna vive dietro l'adapter della propria piattaforma, e il resto del prodotto vede un'unica forma di record connettore. L'adapter registry stessa è gated: in Community è vuota per costruzione, così un'istanza Community fallisce chiusa prima che un traffico esterno raggiunga il workspace.

Modifica: la superficie mutabile di v0.28.1

Prima di v0.28.1, rettificare un connettore significava eliminarlo e ricrearlo. Il cambio della serie v0.28 aggiunge un ramo di modifica: il menu di overflow della scheda porta la voce Edit che apre un dialog pre-compilato su esattamente la superficie mutabile - via PUT /api/connectors/:id:

• Mutabili - il nome, il binding dell'archivio, i messaggi di benvenuto e fallback, il fallback locale, e i due limiti (vuoto = null; 0 = illimitato).
• Immutabili - la piattaforma, il bot token, il workspace.

L'interruttore isEnabled resta sulla scheda (sospende il routing senza cancellare la configurazione), e la mutazione è sotto audit come ogni altra azione admin: l'endpoint registra l'evento chat_connector.updated, alla pari con chat_connector.deleted del ramo DELETE. Il ramo di modifica conta nella storia dell'operatore per un motivo preciso: ricollegare un canale a un archivio ricostruito da zero, o stringere un limite dopo un incidente, non costa più l'identità del connettore.

Il percorso della risposta e il fallback

Ogni domanda che arriva da un canale attraversa la stessa pipeline di un chat interno: ricerca ibrida sull'archivio agganciato, citazione delle fonti, sintesi - poi la risposta citata torna sul canale di partenza. Il binding dell'archivio è il nucleo silenzioso del contract: è ciò che rende fondata una conversazione esterna.

Quando la ricerca non produce elementi validi citabili, la risposta del contract è il messaggio di fallback - una risposta configurata nella fallbackLocale configurata. Un canale esterno non riceve mai una generazione non fondata quando il fallback è in opera; il visitatore legge il fallback invece di un'affermazione sicura senza niente dietro.

I limiti come airlock del workspace

Il rate limit e il daily session limit sono la protezione del contract dal traffico esterno:

• 0 = illimitato (il valore sentinel del router).
• N = il massimo per connettore per le richieste, e per le sessioni al giorno.

Insieme a isEnabled, lasciano che l'operatore esponga la knowledge base a un canale pubblico tenendo il raggio d'azione delimitato: un bot fuori controllo, un canale scraperizzato o un'utenza inattesa consuma al massimo la quota configurata del workspace. Disattivare, stringere o ricollegare - ognuna è ora una modifica singola (il ramo v0.28.1), senza ricreazione.

Per continuare

• Richiedi una demo

La guida porta la procedura completa per l'operatore - il form di creazione campo per campo, la tabella degli adapter per piattaforma, il comportamento di audit - su /it/docs/connectors:

• Connettori - la guida
• La versione in linguaggio semplice
• Fatti in questo post: righe FACT-CENSUS.md F-CONN-1 (il gate d'edizione), F-CONN-2 (il ramo di modifica v0.28.1), F-LIC-1 (l'attivazione incollando la chiave - senza toccare il server)

Provenance: pacchetti Simmetric Chat connector.schema.ts (forme dei campi + limiti), routes/connectors.ts (il router + il limiter), CHANGELOG.md v0.28.1, license.ts (connectors_enabled) allo stato documentale fissato dal census v0.28.1 (SHA aca5b8ff).