Vai al contenuto
Kaiross

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.

RichiestaA cosa serve
GET /agentsAgenti pubblicati del workspace.
POST /agents/{id}/chatDomanda all’agente: message, conversationId facoltativo; risposta in streaming (SSE) o JSON con "stream": false.
GET /agents/{id}/conversations, GET /conversations/{id}/messagesConversazioni e messaggi.
POST /automations/{id}/run, GET /runs/{id}Avvio di un’automazione e stato dell’esecuzione.
POST /actions/{id}/confirm, POST /actions/{id}/cancelConferma o annulla un’azione proposta dall’agente.
Elenco degli agenti
curl https://app.kaiross.ch/api/v1/agents \
  -H "Authorization: Bearer kai_…"
Una domanda, risposta in JSON
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

  1. Pubblica l’agente (scheda Generale → Agente pubblicato (accesso esterno)).
  2. Apri la scheda Widget, attiva Widget attivo e imposta titolo, colore, posizione e messaggio di benvenuto.
  3. In Domini autorizzati (uno per riga) elenca i siti dove comparirà (*.dominio.ch include i sottodomini). Evita *, che lo abilita ovunque.
  4. 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).
  5. 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.
  6. 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.
Pulsante flottante (prima di </body>)
<script src="https://app.kaiross.ch/api/widget.js" data-widget-key="wk_…" async></script>
Chat a tutta pagina
<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.

Scheda Widget di un agente
Scheda Widget di un agente
La scheda Widget: il widget funziona solo con l’agente pubblicato.

Bot Slack

  1. Pubblica l’agente, poi apri la scheda Canali e premi Connetti Slack: autorizza l’app nel tuo workspace Slack.
  2. Nei canali invita l’app (/invite @Kaiross) e menzionala; in privato scrivile dalla sezione App di Slack.
  3. 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

  1. Nel portale Azure crea una risorsa «Azure Bot» (tipo di app: Single Tenant consigliato) e annota App ID e Tenant ID.
  2. In Configurazione imposta il Messaging endpoint mostrato nella scheda Canali; in Canali di Azure aggiungi Microsoft Teams.
  3. Nell’app registrata in Entra ID crea un client secret e incollalo in Kaiross insieme ad App ID e Tenant ID, poi Salva.
  4. 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.

  1. 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.
  2. 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 (o mail), externalId ← objectId; assegna utenti e gruppi e avvia il provisioning.
  3. 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.

  1. Crea prima la connessione in Integrazioni (ad esempio Google Drive o SharePoint).
  2. Nell’agente apri Sincronizzazione → Aggiungi sorgente, scegli la connessione e la Cartella.
  3. 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.

  1. 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.
  2. Premi Copia config.json e salvalo nella cartella del sync-agent: serverUrl è l’indirizzo di Kaiross seguito da /api, watchPath la cartella da sincronizzare.
  3. Prova con npm start, poi installalo come servizio all’avvio (macOS, Windows, Linux) con npm run install-service.
config.json
{
  "serverUrl": "https://app.kaiross.ch/api",
  "token": "ks_…",
  "watchPath": "C:\\Data\\Shared",
  "fullScanMinutes": 30
}
Prova, installazione e rimozione del servizio
npm start
npm run install-service
npm run uninstall-service