Conversation AI Public API

Le API pubbliche di Conversation AI di HITLEAD offrono agli sviluppatori il controllo programmatico su agenti AI, azioni e generazioni di conversazioni. Utilizza token sicuri e scope granulari per automatizzare la configurazione degli agenti, integrarti con applicazioni esterne ed esportare i dati delle conversazioni per analytics o conformità. Questa guida spiega cos'è l'API, i vantaggi, le opzioni di autenticazione (PIT e JWT), le famiglie di endpoint e la configurazione passo-passo con screenshot.

INDICE

Cos'è l'API di Conversation AI?

L'API di Conversation AI espone le stesse funzionalità principali disponibili nell'interfaccia di Conversation AI (creazione e gestione degli agenti, associazione di azioni e recupero dei dettagli delle risposte AI), consentendo al tuo team di automatizzare la configurazione e di connettere Conversation AI ai tuoi sistemi. Tramite questa API puoi effettuare il provisioning degli agenti su larga scala, eseguire script per aggiornare le azioni e recuperare i dati di generazione a livello di messaggio per reportistica e audit.

Questa API è ideale per agenzie, aziende SaaS e sviluppatori che devono gestire Conversation AI su scala, al di là dell'interfaccia utente di HITLEAD.

Cosa puoi fare con le API pubbliche di Conversation AI

Utilizzando l'API, puoi:

  • Creare e gestire gli agenti di Conversation AI
  • Configurare e aggiornare le AI Actions in modo programmatico
  • Recuperare i dati di generazione delle conversazioni AI
  • Automatizzare la configurazione AI su larga scala tra i sub-account
  • Integrare Conversation AI con applicazioni esterne
  • Creare Workflow di reportistica personalizzati e di conformità

Vantaggi principali dell'API di Conversation AI

Comprendere i vantaggi pratici ti aiuta a decidere quando usare l'API anziché l'interfaccia. Questi punti evidenziano i risultati che i team tipicamente automatizzano: provisioning più rapido, configurazione coerente su larga scala e accesso affidabile ai dati dettagliati delle conversazioni.

  • Onboarding più rapido: Automatizza la creazione degli agenti e l'associazione delle azioni per nuove sedi o clienti in pochi minuti.

  • Configurazione scalabile: Applica impostazioni di agenti e azioni coerenti su molti sub-account tramite script o job CI/CD.

  • Analytics avanzate: Recupera le generazioni (dettagli delle risposte AI) per alimentare Dashboard, workflow di QA, audit ed esportazioni per conformità.

  • Integrazione flessibile: Orchestra HITLEAD con i tuoi strumenti interni — attiva Workflow, traccia i risultati e registra eventi in sistemi esterni.

  • Sicurezza least-privilege: Usa scope di sola lettura o di scrittura per limitare l'accesso esattamente a ciò di cui la tua integrazione ha bisogno.

Autenticazione (PIT e JWT)

Scegliere il metodo di autenticazione corretto garantisce un accesso affidabile e sicuro. I Personal Integration Token (PIT) sono facili da generare e configurare con scope, mentre i JSON Web Token (JWT) supportano i flussi di app basati su OAuth. Entrambi possono essere usati per accedere all'API di Conversation AI.

Apri Impostazioni → Private Integrations nel tuo sub-account (location) di HITLEAD.

Schermata 1 — Conversation AI Public API

Fornisci le informazioni di base (nome e descrizione).

Seleziona gli scope di Conversation AI.

Schermata 2 — Conversation AI Public API

Crea il token e salvane una copia.

Schermata 3 — Conversation AI Public API

Gestisci e utilizza il token in modo appropriato.

Schermata 4 — Conversation AI Public API

Documentazione API

Visualizza la documentazione completa delle API qui: Marketplace API 2.0 Conversation AI Actions

Actions

  • Attach Action To Agent
  • List Actions For An Agent
  • Get Action By ID
  • Update Action
  • Remove Action From Agent
  • Update Followup Settings

Agents

  • Create An Agent
  • Search Agents
  • Update Agent
  • Get Agent
  • Delete Agent

Generations

  • Get Generation Details

Domande frequenti

D: Ho bisogno di un token Sub-Account o Agency per Conversation AI?

R: Usa un token Sub-Account in modo che le chiamate operino nel contesto della location corretta.

D: Posso gestire gli agenti di Conversation AI tramite API?

Sì. L'API ti consente di creare, aggiornare, recuperare e gestire gli agenti di Conversation AI in modo programmatico.

D: Posso usare sia PIT che JWT?

R: Sì. Puoi autenticarti con entrambi i metodi. Scegli PIT per le integrazioni semplici server-to-server; usa JWT per i flussi di app OAuth.

D: Dove trovo l'agentId?

R: Crea o cerca agenti tramite l'API Agents, poi usa il campo id restituito nelle chiamate successive.

D: Come posso controllare le risposte AI in modo programmatico?

R: Usa l'endpoint Generations per recuperare i dettagli delle risposte a livello di messaggio e archiviarli nel tuo sistema di analytics o conformità.

D: Perché ricevo un errore 403?

Di solito è causato da scope mancanti, permessi errati, oppure dal tentativo di accedere a risorse al di fuori del Sub-Account autorizzato.