Costruisci sopra iNTELIGENCIA VIVA
L'API pubblica è il punto di estensione per qualsiasi cosa uno sviluppatore voglia costruire sopra un workspace: instradare le conversazioni verso un proprio sistema, dare a un agente IA uno strumento che interroga l'ERP di un cliente, sincronizzare i contatti con un CRM, o trasmettere eventi in tempo reale verso una propria dashboard. È REST, versionata come v1, e ogni risorsa del modello dati del prodotto è raggiungibile attraverso di essa.
Autenticazione
Ogni richiesta viene autenticata con una chiave API emessa dal pannello del workspace, inviata come `Authorization: Bearer sk_live_...`.
Ogni chiave ha il proprio ambito di permessi configurabile — una chiave può essere limitata all'accesso in sola lettura, a risorse specifiche, oppure ricevere accesso completo in lettura e scrittura, indipendentemente da qualsiasi altra chiave emessa per lo stesso workspace.
Le chiavi vengono mostrate per intero una sola volta, nel momento in cui vengono create; da quel momento in poi solo il loro titolare può rivederle, e ogni chiave può essere revocata immediatamente dal pannello senza influire sulle altre.
Authorization: Bearer sk_live_...Risorse
Ogni risorsa del modello dati sottostante è disponibile tramite l'API:
| Workspace | Configurazione generale, lingua predefinita, canali attivi. |
| Contact | Creazione, ricerca e consultazione dei clienti finali che scrivono. |
| Conversation | Elenco, creazione, chiusura e riassegnazione delle conversazioni. |
| Message | Invio e lettura dei messaggi all'interno di una conversazione. |
| Department | Gestione dei team e delle loro regole di instradamento. |
| Agent | Gestione degli utenti umani, dei ruoli e dell'appartenenza ai reparti. |
| AIAgent | Creazione e configurazione di agenti IA: istruzioni, base di conoscenza, strumenti richiamabili. |
| KnowledgeSource | Caricamento e gestione di documenti e URL per il RAG. |
| Channel | Configurazione dei canali e delle loro credenziali. |
| Webhook | Iscrizione a eventi in uscita, firmati con HMAC. |
| APIKey | Emissione e revoca delle chiavi. |
Eventi webhook
Iscrivi un `WebhookEndpoint` a uno qualsiasi di questi eventi; ogni consegna è firmata con HMAC usando il segreto associato a quell'endpoint, così puoi verificare che provenga davvero da noi prima di fidarti del suo contenuto:
| conversation.created | È iniziata una nuova conversazione su un canale qualsiasi. |
| conversation.assigned | Una conversazione è stata assegnata a un agente umano o a un reparto. |
| conversation.resolved | Una conversazione è stata chiusa, dall'IA o da un umano. |
| message.received | È arrivato un nuovo messaggio in entrata da un contatto. |
| message.sent | È stato inviato un messaggio a un contatto, dall'IA o da un agente. |
| handoff.requested | La sicurezza dell'IA è scesa sotto la soglia del workspace e ha richiesto un umano. |
| ai_agent.tool_call | Un agente IA ha invocato uno dei suoi strumenti configurati, inclusi strumenti che hai registrato tu stesso. |
Le consegne vengono ritentate in caso di errore e non è garantita l'esattamente-una-volta — progetta il tuo gestore di webhook in modo che sia idempotente. La semantica completa di consegna e nuovi tentativi è documentata nei Termini API per Sviluppatori.
Streaming in tempo reale
Per le integrazioni che devono consumare eventi dal vivo invece che, o in aggiunta a, i webhook, ogni workspace espone un endpoint di streaming WebSocket:
wss://api.inteligenciaviva.com/v1/workspaces/{id}/streamLimiti di frequenza e uso corretto
L'accesso all'API è soggetto a limiti di frequenza legati al piano del tuo workspace; una richiesta oltre il limite viene segnalata con HTTP 429 e gli header di limite di frequenza correnti, così puoi implementare correttamente un backoff. I limiti esatti e i termini pienamente vincolanti dell'uso dell'API — incluso cosa puoi e cosa non puoi fare con i dati che ottieni — sono stabiliti nei Termini API per Sviluppatori, collegati dalla pagina Legale.