Connettori — canali esterni connessi al knowledge base
I connettori collegano i canali di messaggistica dove si trovano già i vostri clienti e colleghi — WhatsApp, Telegram, Discord, Slack — alla stessa knowledge base che alimenta il chat interno. Le conversazioni restano sui vostri server: l'app interroga l…
I connettori collegano i canali di messaggistica dove si trovano già i vostri clienti e colleghi — WhatsApp, Telegram, Discord, Slack — alla stessa knowledge base che alimenta il chat interno. Le conversazioni restano sui vostri server: l'app interroga le API del canale con le credenziali che l'amministratore inserisce, e le risposte provengono dal knowledge base documentale.
Disponibile nell'edizione Enterprise (connectors_enabled: falsenella licenza Community — l'admin panel Community mostra l'UpgradePrompt; vedi Administration). Riferimento:packages/shared/src/schemas/connector.schema.ts(i campi del form),packages/server/src/routes/connectors.ts(i limiti e il router),CHANGELOG.mdv0.28.1,packages/shared/src/constants/license.ts. Righe di provenienza:FACT-CENSUS.mdF-CONN-1, F-CONN-2, F-LIC-1.
Creare un connettore
Percorso: Settings → Conversations → Connectors (pulsante New connector). Il form richiede:
| Campo | Note |
|---|---|
| Nome | identificativo dell'istanza connettore |
| Piattaforma | telegram, discord, slack, whatsapp — immutabile dopo la creazione |
| Bot token / credenziali | il token segreto del canale — immutabile dopo la creazione (solo create; la PUT non lo tocca) |
| Workspace | il workspace di binding, immutabile |
| Knowledge archive binding | l'archivio documentale che alimenta le risposte |
| Messaggio di benvenuto | il primo messaggio che il canale invia a chi scrive (max 4000 caratteri) |
| Messaggio di fallback | la risposta quando la ricerca non produce fonti valide (max 4000 caratteri) |
| Fallback locale | la lingua del messaggio di fallback |
| Rate limit | 0 = illimitato (sentinel del router), N = massimo N richieste |
| Daily session limit | 0 = illimitato, N = massimo N sessioni al giorno |
Il binding dell'archivio determina il corpus: ogni domanda che arriva dal canale attraversa la stessa pipeline RAG delle chat interne (ricerca ibrida, source citation, synthesis) — la risposta citata viene rimandata sul canale di partenza.
Modificare un connettore (v0.28.1)
La scheda del connettore nel pannello admin espone il menu di overflow con la voce Edit (primo item): apre un dialog pre-compilato sulla superficie mutabile:
- Mutabili via `PUT /api/connectors/:id`: nome, binding dell'archivio, messaggi di benvenuto/fallback, fallback locale, rate limit, daily session limit (vuoto = null;
0= illimitato). - Immutabili per schema: piattaforma, bot token, workspace. Cambiate canale o token = nuovo connettore.
- L'interruttore
isEnabledresta sulla scheda (Switch); il TelegrampollModeresta sui bottoni webhook. - La PUT registra l'evento di audit
chat_connector.updated(alla pari con il ramo DELETE).
Adapter per piattaforma
Ogni piattaforma ha un adapter dedicato con le sue credenziali di registro:
| Piattaforma | credenziali | note |
|---|---|---|
| Telegram | bot token (@BotFather) | supporto poll mode (polling) e webhook (bottoni dedicati sulla scheda) |
| Discord | bot token (Developer Portal) + intenti messaggio | gli adapter leggono i canali autorizzati dal bot |
| Slack | bot token + signing secret (Slack app) | eventi messaggio via webhook configurato |
| provider Business API (token segreto) | l'adapter usa l'API del provider |
Le credenziali transitano e restano lato server; il token segreto non viene mai riflesso in interfaccia dopo la creazione.
Limiti e messaggio fallback
Il rate limit e il daily session limit proteggono il workspace dal traffico esterno: 0 = illimitato; N = il massimo per connettore. Il messaggio di fallback (fallback locale configurabile) è la risposta quando la ricerca nel corpus non produce elementi validi citabili — il canale esterno non riceve mai generazioni senza fonti quando il fallback è configurato.
Disattivazione e audit
isEnabled(Switch sulla scheda) sospende il routing senza cancellare la configurazione.- Il DELETE del connettore è un'azione dedicata con audit (l'evento
chat_connector.deletedalla pari con l'updated). - Tutte le operazioni admin sui connettori finiscono nell'event log (vedi Administration).
Attivazione Enterprise senza toccare il server
La licenza Enterprise si applica incollando la chiave nel pannello (Settings → Security → License, GET/PUT/DELETE /api/license/instance): verifica probe-first della chiave (invalid/expired/plugin_bound/community_tier — una chiave rifiutata non persiste mai), ciphertext AES-256-GCM in SystemConfig, applicazione a runtime via setCachedLicense. Vedi API reference per l'endpoint; F-LIC-1.
Questa guida copre la superficie operativa degli adapter dei connettori; l'approfondimento tecnico vive nel post gemello:
Provenance
| Sezione | Fonte |
|---|---|
| Gate edizione / UpgradePrompt | packages/shared/src/constants/license.ts (connectors_enabled) — F-CONN-1 |
| Superficie Edit + immutabili + audit | CHANGELOG.md v0.28.1 (Added, Q1-quick; Phase 221 per la licenza) — F-CONN-2, F-LIC-1 |
| Campi del form / limiti | packages/shared/src/schemas/connector.schema.ts (welcomeMessage/fallbackMessage max 4000, fallbackLocale, rateLimitPerMinute/sessionLimitPerDay - il limiter traduce 0 → unlimited) |
---
Riferimento operativo — Simmetric Chat v0.28.1 (documenti aggiornati 2026-10-02, census SHA `aca5b8ff`).