Documentazione API — REST v1, webhook e streaming

Quickstart: la tua prima richiesta in 60 secondi

Crea una chiave API nel tuo workspace, esportala ed elenca le tue conversazioni. Le chiavi hanno ambito per workspace e possono essere in sola lettura o in lettura-scrittura.

curl https://api.inteligenciaviva.com/v1/workspaces/WORKSPACE_ID/conversations \
  -H "Authorization: Bearer sk_live_..."

Ogni risposta è JSON. Gli endpoint di collezione restituiscono array `data`; gli errori restituiscono un oggetto `error` con `code` e `message` e lo stato HTTP corrispondente.

L'API gratuita — senza account, senza chiave

Anche il livello gratuito parla API. `POST /v1/free/widget-snippet` riceve esattamente la stessa configurazione che il generatore visuale costruisce nella pagina Gratis e restituisce lo snippet HTML pronto da incollare — senza autenticazione, senza registrazione. Usala per generare widget in blocco per i siti dei clienti, rigenerare gli embed dalla CI quando cambiano gli orari, o semplicemente per toccare l'API prima di pagare un centesimo.

curl -X POST https://api.inteligenciaviva.com/v1/free/widget-snippet \
  -H "Content-Type: application/json" \
  -d @widget-config.json
# → { "snippet": "<link rel=\"stylesheet\" ..." }

Autenticazione

Ogni richiesta porta una chiave API nell'header `Authorization` come token Bearer. Le chiavi si creano e si revocano dall'API stessa o dal pannello, per workspace — revocare una chiave taglia il suo accesso immediatamente.

Gli endpoint di sessione a livello di account (registrazione, login, accesso con Google, scambio di ticket, profilo ed eliminazione dell'account sotto `/v1/auth`) alimentano le nostre stesse app; per le integrazioni server-to-server preferisci sempre le chiavi API di workspace alle sessioni utente.

Authorization: Bearer sk_live_...

Riferimento delle risorse

Tutte le rotte qui sotto pendono da `https://api.inteligenciaviva.com/v1/workspaces/{workspaceId}` salvo dove indicato. Questa è la superficie reale montata del backend attuale — niente di aspirazionale.

Posta combinata `/inbox`

GET	/conversations	Tutte le conversazioni di TUTTI gli spazi che questa credenziale segue, in un unico elenco ordinato per attività.
GET	/conversations/{id}	Una conversazione cercata in tutti i tuoi spazi, senza sapere in quale si trova. Restituisce il workspace_id.
GET	/workspaces	Gli spazi che questa credenziale può seguire, con il ruolo in ciascuno.

Conversazioni `/conversations`

GET	/	Elenca le conversazioni, filtrabili per stato.
GET	/{id}	Una conversazione con stato, canale, contatto e assegnazione.
GET	/{id}/messages	Cronologia dei messaggi (visitatore, agente umano, IA, sistema).
POST	/{id}/messages	Invia un messaggio nella conversazione come agente.
POST	/{id}/assign	Assegna la conversazione a un agente umano o a un reparto.
POST	/{id}/resolve	Chiudi la conversazione. Se l'IA l'ha chiusa da sola, conta come risoluzione fatturabile.
POST	/	Aprire una conversazione fuori dal widget (per esempio per migrare un thread esistente).
GET	/{id}/ai-turns	«Da dove l’ha preso?» — il registro di ogni turno di IA: su cosa si è basata, con quale modello, quanto ha impiegato e perché ha trasferito.
GET	/{id}/portal-case	Stato del caso che questa conversazione ha aperto nella bacheca di supporto del Portale, con le sue risposte. Si consulta in tempo reale.
POST	/{id}/read	Segnare la conversazione come letta dal team (contatore dei non letti).
POST	/{id}/reopen	Riaprire una conversazione chiusa mantenendo lo storico. Senza questo, una chiusura per errore non aveva ritorno.
POST	/{id}/archive	Archivia o togli dall'archivio. Esce dalla posta senza chiudersi né perdere nulla; il corpo è {valor:true\|false}.
POST	/{id}/pin	Fissa in alto o rilascia. Le fissate aprono la prima pagina della posta. Corpo: {valor:true\|false}.
POST	/{id}/mute	Silenzia gli avvisi per N ore, o {horas:null} per tornare a sentirla.
POST	/{id}/unread	Lasciarla non letta: il segno di lettura torna dietro all'ultimo messaggio del cliente.

Contatti `/contacts`

GET	/	Elenca i contatti.
GET	/{id}	Un contatto con le sue identità e la cronologia delle conversazioni.

Agenti IA `/ai-agents`

GET	/	Elenca gli agenti IA del workspace.
POST	/	Crea un agente IA: istruzioni, reparto, soglia di confidenza.
PATCH	/{id}	Aggiorna istruzioni, soglia o reparto.
GET	/{id}/knowledge-sources	Fonti di conoscenza collegate a questo agente.
POST	/{id}/knowledge-sources	Collega una fonte di conoscenza a questo agente.
GET	/{aiAgentId}	Un agente IA: istruzioni, soglia di confidenza, strumenti e reparto.

Conoscenza (RAG) `/knowledge-sources`

POST	/document	Indicizza un documento come conoscenza fondata.
POST	/url	Indicizza un URL.
GET	/{id}	Stato e metadati della fonte.
DELETE	/{id}	Rimuovi una fonte e i suoi vettori.
POST	/{id}/reindex	Rileggere una fonte URL senza eliminarla: se il download fallisce, non si tocca nulla.
GET	/	Elencare le fonti di conoscenza con il loro stato di indicizzazione.

Canali `/channels`

GET	/	Elenca i canali. Vivi oggi: chat web e API; altri si collegano man mano che escono.
PUT	/{id}/credentials	Imposta le credenziali di un canale.
PUT	/{id}/status	Abilita o disabilita un canale.
POST	/	Creare un canale.
GET	/{channelId}	Un canale con tipo, stato e impostazioni.
GET	/{channelId}/snippet	L’unica riga che il cliente incolla nel suo sito. Tutto il resto si configura qui.
GET	/{channelId}/config	La configurazione della chat: il pubblicato (`config`) e ciò che questo canale sovrascrive (`settings`). Sono cose diverse.
PUT	/{channelId}/config	Salvare la configurazione. Salvare e pubblicare sono lo stesso passo: se la CDN fallisce, fallisce il PUT.
POST	/{channelId}/config/publish	Ripubblicare la configurazione sulla CDN senza modificarla.
POST	/{channelId}/avatar	Caricare il volto dell’assistente (≤512 KB). Va su R2 ed è servito dalla CDN.
POST	/republicar-todos	Ripubblicare tutti i canali del workspace. Lo fa il cron quando cambia il pacchetto di stringhe; questo evita l’attesa.

Agenti umani e reparti `/agents · /departments`

GET	/agents	Elenca gli agenti umani del workspace.
POST	/agents/{userId}/departments	Metti un agente in un reparto.
GET	/departments	Elenca i reparti.
PUT	/departments/{id}/routing-rules	Imposta le regole di instradamento delle conversazioni in entrata.
POST	/agents	Invitare una persona nel workspace, con ruolo e reparti.
GET	/agents/{userId}	Una persona del team.
POST	/departments	Creare un reparto con le sue regole di instradamento.
GET	/departments/{id}	Un reparto.

Webhook, chiavi, fatturazione, statistiche `/webhooks · /api-keys · /billing · /analytics`

POST	/webhooks	Registra un endpoint; ricevi il suo segreto di firma una sola volta.
DELETE	/webhooks/{id}	Rimuovi un endpoint.
POST	/api-keys	Crea una chiave (sola lettura o lettura-scrittura).
DELETE	/api-keys/{id}	Revoca una chiave immediatamente.
GET	/billing/subscription	Piano, risoluzioni IA incluse e uso del periodo.
GET	/analytics	Metriche aggregate del workspace.
GET	/webhooks	Elencare gli endpoint webhook.
GET	/webhooks/{id}/deliveries	Storico delle consegne di un webhook, con i tentativi. È ciò che dice se l’errore è vostro o nostro.
GET	/api-keys	Elencare le chiavi. Il segreto non viene mai restituito: solo il prefisso.

Strumenti dell'agente `/conversations/{id} · /canned-responses · /tags · /presence`

GET	/conversations/{id}/notes	Note interne della conversazione. Il visitatore non le vede mai.
POST	/conversations/{id}/notes	Aggiungere una nota interna.
DELETE	/conversations/{id}/notes/{noteId}	Eliminare una nota interna.
GET	/canned-responses	Risposte predefinite del workspace, con la loro scorciatoia.
POST	/canned-responses	Creare una risposta predefinita.
PATCH	/canned-responses/{cannedId}	Modificare una risposta predefinita.
DELETE	/canned-responses/{cannedId}	Eliminare una risposta predefinita.
POST	/presence	Battito di presenza: dichiara che c’è una persona disponibile. Solo con sessione — una chiave API che batte non è qualcuno davanti allo schermo, e viene rifiutata con 400.
GET	/presence	C’è qualcuno online adesso? È ciò che decide se un passaggio attende o viene deviato.
GET	/ai-usage	Consumo di inferenza del workspace per giorno e le conversazioni più costose.
GET	/tags	Etichette del workspace.
GET	/conversations/{id}/tags	Etichette di una conversazione.
POST	/conversations/{id}/tags	Etichettare una conversazione. Crea l’etichetta se non esisteva.
DELETE	/conversations/{id}/tags/{tagId}	Rimuovere un’etichetta dalla conversazione.
POST	/conversations/{id}/transfer	Trasferire la conversazione a un reparto. Prevale sulle regole di instradamento: un trasferimento manuale non si annulla da solo.
POST	/contacts/{contactId}/block	Bloccare un contatto. Riceve un 403 senza dettagli: a chi abusa non si spiega come è stato rilevato.

Allegati, dispositivi e workspace `/conversations/{id}/attachments · /devices · /workspaces`

POST	/conversations/{id}/attachments	Caricare un allegato come agente. Allowlist rigida e 10 MB: non entra nulla che un browser possa eseguire.
GET	/conversations/{id}/attachments	Allegati di una conversazione.
GET	/attachments/{attachmentId}	Scaricare un allegato. Servito con header rigidi e `nosniff`; solo immagini e audio si mostrano in linea.
POST	/devices/register	Registrare il token push di un dispositivo, per avvisare una persona quando l’IA trasferisce. Fuori dal prefisso workspace: `/v1/devices/register`.
POST	/workspaces	Creare un workspace. Fuori dal prefisso: `/v1/workspaces`.

Esempi reali

Invia un messaggio da agente (curl)

curl -X POST \
  https://api.inteligenciaviva.com/v1/workspaces/$WS/conversations/$CONV/messages \
  -H "Authorization: Bearer $IV_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hi! I checked your order — it ships tomorrow."}'

Elenca le conversazioni (JavaScript)

const res = await fetch(
  `https://api.inteligenciaviva.com/v1/workspaces/${WS}/conversations`,
  { headers: { Authorization: `Bearer ${process.env.IV_KEY}` } }
);
const { data } = await res.json();

Verifica la firma di un webhook (Node)

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, rawBody, header, toleranceSec = 300) {
  const { t, v1 } = Object.fromEntries(
    header.split(",").map((p) => p.split("="))
  );
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false;
  const expected = createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Webhook

Registra un endpoint HTTPS e ti inviamo ogni evento via POST, firmato. L'header è `iv-signature: t=<unix>,v1=<hex>`, dove `v1` è l'HMAC-SHA256 di `<timestamp>.<body grezzo>` con il segreto del tuo endpoint — rifiuta tutto ciò che ha più di 5 minuti (protezione dai replay). Le consegne fallite vengono ritentate automaticamente con una firma fresca, fino a 5 tentativi.

conversation.created	È iniziata una nuova conversazione su un canale qualsiasi.
message.created	È arrivato un messaggio (visitatore, umano, IA o sistema).
handoff.requested	L'IA ha deciso che le serve un umano — il momento esatto, con il riepilogo.
conversation.resolved	Una conversazione è stata chiusa; ti dice se l'IA l'ha chiusa da sola.

Ogni consegna e il suo stato restano registrati — un webhook di cui non puoi fidarti è peggio di nessuno.

Streaming in tempo reale

Per le interfacce dal vivo, apri un WebSocket verso lo stream del workspace e ricevi gli eventi delle conversazioni mentre accadono — lo stesso canale che usano le nostre stesse app per agenti.

wss://api.inteligenciaviva.com/v1/workspaces/{workspaceId}/stream

Errori e limiti

Gli errori sono HTTP convenzionale: `400` richiesta malformata, `401` chiave assente o non valida, `403` chiave senza permessi, `404` risorsa non presente in questo workspace, `429` limite di frequenza (attendi e riprova con jitter), `5xx` colpa nostra — riprova le richieste idempotenti. Il body porta sempre un `error.code` e un `error.message` leggibile da un umano. I limiti di frequenza sono per chiave e generosi per le integrazioni reali.

Domande frequenti

Questa documentazione è aspirazionale o è la superficie reale?

Reale. È scritta contro le rotte montate del backend attuale. Quando qui qualcosa dice "in arrivo", vuol dire che non esiste ancora — non documentiamo fumo.

Serve un piano a pagamento per usare l'API?

Sì — l'API fa parte della piattaforma a pagamento (Pro la include). Il Widget gratuito e il plugin per WordPress sono lato client e non hanno bisogno di alcuna API.

Qual è la differenza tra chiavi in sola lettura e in lettura-scrittura?

Le chiavi in sola lettura possono elencare e consultare ma mai modificare — ideali per dashboard e BI. Quelle in lettura-scrittura possono creare messaggi, contatti, agenti IA e configurazione.

Come vengo avvisato dei nuovi messaggi — polling o webhook?

Webhook (`message.created`) per i server, lo stream WebSocket per le interfacce dal vivo. Il polling funziona, ma sbatterai contro i limiti di frequenza prima di arrivare al tempo reale.

Come verifico esattamente che un webhook arriva da voi?

Ricalcola l'HMAC-SHA256 di `<t>.<body grezzo>` con il segreto del tuo endpoint e confrontalo in tempo costante con il valore `v1` dell'header `iv-signature`; rifiuta se `t` ha più di 300 secondi. Il codice funzionante è in questa pagina.

Cosa succede se il mio endpoint webhook è giù?

Registriamo la consegna fallita e riproviamo automaticamente con timestamp e firma freschi, fino a 5 tentativi. Se nel frattempo l'endpoint è stato eliminato o disabilitato, i tentativi si fermano in modo pulito.

L'IA può passare la mano al mio sistema di escalation?

Sì — è esattamente per questo che esiste `handoff.requested`. Scatta nel momento in cui la confidenza dell'IA scende sotto la soglia del workspace, con il riepilogo della conversazione, così puoi avvisare una persona o aprire un ticket altrove.

Quali canali posso pilotare tramite l'API oggi?

La chat web è viva da un capo all'altro, e tutto ciò che c'è in questo riferimento funziona oggi. Telegram e altri canali di messaggistica si collegano allo stesso modello di conversazione man mano che escono — la tua integrazione non cambia.

Esiste un SDK?

Un SDK Flutter alimenta la nostra stessa app per agenti ed è la base dell'SDK white-label di Enterprise. Per i server, la superficie REST è volutamente semplice — qualsiasi client HTTP funziona senza wrapper.

Dove segnalo un bug dell'API o una lacuna in questa documentazione?

Scrivi a l@inteligenciaviva.com. Anche una documentazione che mente è un bug — la trattiamo con la stessa severità.

Costruisci sulla stessa API su cui costruiamo noi

Quickstart: la tua prima richiesta in 60 secondi

L'API gratuita — senza account, senza chiave

Autenticazione

Riferimento delle risorse

Posta combinata /inbox

Conversazioni /conversations

Contatti /contacts

Agenti IA /ai-agents

Conoscenza (RAG) /knowledge-sources

Canali /channels

Agenti umani e reparti /agents · /departments

Webhook, chiavi, fatturazione, statistiche /webhooks · /api-keys · /billing · /analytics

Strumenti dell'agente /conversations/{id} · /canned-responses · /tags · /presence

Allegati, dispositivi e workspace /conversations/{id}/attachments · /devices · /workspaces