API, widget, Slack, Teams, SCIM e sorgenti sincronizzate
Gli agenti pubblicati rispondono anche fuori dall’app: dal tuo sito, da Slack e Teams o dai tuoi programmi. E la knowledge resta allineata alle cartelle dell’azienda.
Ultimo aggiornamento:
API REST
Base: https://app.kaiross.ch/api/v1, con l’header Authorization: Bearer kai_… (chiave da Impostazioni → Chiavi API, vedi come crearla). Gli agenti devono essere pubblicati. Il riferimento completo (OpenAPI 3.1) è nella pagina API e MCP dell’app, con esempi in cURL, Node.js e Python.
| Richiesta | A cosa serve |
|---|---|
GET /agents | Agenti pubblicati del workspace. |
POST /agents/{id}/chat | Domanda all’agente: message, conversationId facoltativo; risposta in streaming (SSE) o JSON con "stream": false. |
GET /agents/{id}/conversations, GET /conversations/{id}/messages | Conversazioni e messaggi. |
POST /automations/{id}/run, GET /runs/{id} | Avvio di un’automazione e stato dell’esecuzione. |
POST /actions/{id}/confirm, POST /actions/{id}/cancel | Conferma o annulla un’azione proposta dall’agente. |
curl https://app.kaiross.ch/api/v1/agents \
-H "Authorization: Bearer kai_…" curl https://app.kaiross.ch/api/v1/agents/<agent-id>/chat \
-H "Authorization: Bearer kai_…" \
-H "Content-Type: application/json" \
-d '{"message": "…", "stream": false}' Limiti per chiave: 120 richieste al minuto, di cui 30 chat. Le risposte di chat hanno l’header X-AI-Generated: true.
Widget per il sito
- Pubblica l’agente (scheda Generale → Agente pubblicato (accesso esterno)).
- Apri la scheda Widget, attiva Widget attivo e imposta titolo, colore, posizione e messaggio di benvenuto.
- In Domini autorizzati (uno per riga) elenca i siti dove comparirà (
*.dominio.chinclude i sottodomini). Evita*, che lo abilita ovunque. - Imposta Messaggi massimi all’ora (predefinito 300) e, se vuoi, il testo dell’Avviso AI: vuoto = testo predefinito nella lingua del visitatore (EU AI Act, art. 50).
- In Informativa sulla privacy indica l’indirizzo https dell’informativa del tuo sito: i visitatori la vedono accanto all’avviso e deve citare l’assistente.
- Salva e copia lo snippet da Installazione nel sito. Anteprima apre il widget in una nuova scheda, con l’agente pubblicato e il widget attivo e salvato.
<script src="https://app.kaiross.ch/api/widget.js" data-widget-key="wk_…" async></script> <iframe src="https://app.kaiross.ch/api/widget/wk_…/frame" title="Kaiross"
style="width:100%;height:640px;border:0;border-radius:12px"></iframe> Il widget segue la lingua della pagina; data-lang="it|de|fr|en" la forza. Le Azioni automatiche per i visitatori sono spente di default: lasciale spente se l’agente ha strumenti che scrivono.
In Conversazioni dei visitatori leggi le conversazioni arrivate dal widget. I visitatori possono cancellare la propria dal widget, e su richiesta ne elimini una tu con Elimina la conversazione. Per quanto tempo restano lo decidi in Dati e conservazione.
Bot Slack
- Pubblica l’agente, poi apri la scheda Canali e premi Connetti Slack: autorizza l’app nel tuo workspace Slack.
- Nei canali invita l’app (
/invite @Kaiross) e menzionala; in privato scrivile dalla sezione App di Slack. - Premi Invia prova per verificare.
Il bot risponde solo a chi è membro del workspace Kaiross e può usare l’agente: gli utenti Slack sono riconosciuti dall’email.
Bot Microsoft Teams
- Nel portale Azure crea una risorsa «Azure Bot» (tipo di app: Single Tenant consigliato) e annota App ID e Tenant ID.
- In Configurazione imposta il Messaging endpoint mostrato nella scheda Canali; in Canali di Azure aggiungi Microsoft Teams.
- Nell’app registrata in Entra ID crea un client secret e incollalo in Kaiross insieme ad App ID e Tenant ID, poi Salva.
- Premi Scarica pacchetto app e caricalo in Teams (App → Gestisci app → Carica un’app) o nel Teams Admin Center per tutta l’azienda.
Provisioning SCIM (Entra ID, Okta)
Con SCIM gli utenti del tuo Identity Provider diventano membri del workspace e i gruppi corrispondono ai ruoli Kaiross con lo stesso nome. Disattivare un utente toglie l’accesso al workspace.
- In Impostazioni → Sicurezza workspace → Provisioning SCIM copia l’URL base SCIM (
https://app.kaiross.ch/api/scim/v2) e premi Genera token. Copia il token subito: non sarà più visibile. - Microsoft Entra ID: Applicazioni aziendali → Nuova applicazione → Crea la tua applicazione; Provisioning → Automatico con URL tenant = URL base SCIM e Token segreto = token; mapping
userName←userPrincipalName(omail),externalId←objectId; assegna utenti e gruppi e avvia il provisioning. - Okta: Applications → Create App Integration, abilita SCIM provisioning; SCIM connector base URL = URL base SCIM, Unique identifier =
userName, Authentication = HTTP Header (Bearer) con il token; in To App abilita Create Users, Update User Attributes e Deactivate Users; con Push Groups collega i gruppi ai ruoli.
Kaiross non rimuove mai l’ultimo amministratore: la richiesta viene rifiutata.
Sorgenti sincronizzate
Una sorgente tiene la knowledge dell’agente allineata a una cartella: file nuovi e modificati vengono indicizzati, quelli rimossi eliminati. Servizi: Google Drive, SharePoint/OneDrive, Dropbox, Box, S3, FTP/SFTP e cartelle locali con il sync-agent.
- Crea prima la connessione in Integrazioni (ad esempio Google Drive o SharePoint).
- Nell’agente apri Sincronizzazione → Aggiungi sorgente, scegli la connessione e la Cartella.
- Imposta Frequenza, Includi le sottocartelle, Dimensione massima (MB) ed eventuali filtri (Solo questi formati, Escludi percorsi che contengono), poi Crea e sincronizza.
Rispetta i permessi della fonte (attivo di default): ogni documento è visibile in chat solo a chi può aprirlo nella fonte (utenti, domini e gruppi di Drive, SharePoint, Dropbox o Box). Disattivandolo, tutti gli utenti dell’agente vedono tutti i documenti sincronizzati.
Cartelle locali: sync-agent
Per una cartella su un PC o un file server, il sync-agent è un piccolo programma (Node.js 20 o successivo, nessuna dipendenza da installare) che invia a Kaiross i file nuovi o modificati. Il pacchetto del sync-agent te lo fornisce Kaiross.
- Nell’agente: Sincronizzazione → Aggiungi sorgente → Da dove: Cartella del PC o server (sync-agent) → Crea e genera token. Il token (
ks_…) si vede una volta sola. - Premi Copia config.json e salvalo nella cartella del sync-agent:
serverUrlè l’indirizzo di Kaiross seguito da/api,watchPathla cartella da sincronizzare. - Prova con
npm start, poi installalo come servizio all’avvio (macOS, Windows, Linux) connpm run install-service.
{
"serverUrl": "https://app.kaiross.ch/api",
"token": "ks_…",
"watchPath": "C:\\Data\\Shared",
"fullScanMinutes": 30
} npm start
npm run install-service
npm run uninstall-service