Come configurare un'integrazione API personalizzata con AI Assist

L’AI Assist di tawk.to supporta integrazioni API personalizzate che permettono al tuo agente AI di eseguire automaticamente ricerche e azioni nel backend, proprio come farebbe un operatore umano.

Ad esempio, il tuo agente AI può:

• Cercare nel catalogo prodotti
• Controllare lo stato di un ordine o di un pagamento
• Verificare i dettagli di fatturazione
• Recuperare gli acquisti passati




Questo consente ai clienti di ottenere risposte immediate senza dover aspettare un operatore umano.
Le integrazioni API sono configurate per ogni proprietà. Se utilizzi più agenti AI, puoi attivare o disattivare ogni integrazione singolarmente per ciascun agente.

Questa guida include:

• Cosa serve prima di iniziare
• Come configurare l’integrazione in tawk.to
• Come testare l’integrazione
• Un riferimento tecnico per gli sviluppatori che devono creare l’API




Nota: le integrazioni sono disponibili solo con i piani Growth, Business ed Enterprise.

Prima di iniziare

Per configurare un’integrazione API personalizzata, ti serviranno:

• Un endpoint API

Un URL a cui AI Assist può inviare richieste e da cui ricevere dati.

• Uno schema OpenAPI

Un file che descrive gli endpoint della tua API, i parametri e le risposte, in modo che AI Assist sappia come utilizzarla.

• Credenziali di autenticazione (se richieste)

Ad esempio: chiave API, nome utente e password, oppure altri metodi di autenticazione supportati dalla tua API.


Usi Shopify, WooCommerce o BigCommerce?

Invece di un’integrazione API personalizzata, puoi utilizzare le integrazioni native di tawk.to. Consulta queste guide per istruzioni passo-passo:

• Come integrare AI Assist con Shopify
• Come integrare AI Assist con WooCommerce
• Come integrare AI Assist con BigCommerce

Per altre piattaforme

• Wix
• Squarespace
• Magento
• PrestaShop
• Un prodotto SaaS con una propria API
• Un sistema backend personalizzato

— avrai bisogno di uno sviluppatore per creare l’endpoint API e lo schema OpenAPI.
Se la tua piattaforma non espone direttamente un’API, lo sviluppatore potrebbe dover creare un servizio proxy. Alcuni strumenti comunemente usati per questo scopo includono:

• Google Apps Script
• Cloudflare Workers
• Un server Node.js

Se non ti senti a tuo agio a realizzare questa integrazione da solo, puoi condividere questa guida con uno sviluppatore. La sezione “Riferimento tecnico per sviluppatori” qui sotto spiega esattamente cosa deve essere implementato.

Aggiungere l’integrazione in tawk.to

1. Accedi al tuo account tawk.to e seleziona la proprietà corretta.

2.Fai clic su Automation nella barra di navigazione a sinistra.

3. Fai clic su Integrazioni nel sottomenu a sinistra.

4. Fai clic su OpenAPI Server sotto Strumento personalizzato.

5. Si aprirà la pagina di panoramica di OpenAPI Server. Fai clic su Installa nell’angolo in alto a destra.

• GitHub (utilizzando l’URL del file Raw)
• GitHub Gist
• Amazon S3
• Qualsiasi servizio di hosting web

• No Auth — se la tua API non richiede autenticazione.
• API key — inserisci Key e Value.
  (es. key: “x-api-key”, value: “la-tua-chiave-segreta”)

• Basic — inserisci il tuo nome utente e password.

8. Fai clic su Salva.

9. Dopo aver salvato, fai clic su Agenti nel sottomenu a sinistra.

10. Seleziona il tuo agente AI. Quindi, fai clic su Tools nel menu a sinistra e assicurati che l’integrazione sia attiva sotto Status.

Se le descrizioni nel tuo schema sono chiare e specifiche, AI Assist dovrebbe richiamare automaticamente gli endpoint API corretti.

“Se il cliente chiede informazioni sullo stato dell’ordine, usa la chiamata API trackOrder.”

Prima di distribuire la tua integrazione, testala attentamente.

Usa uno strumento come Postman o un browser per chiamare il tuo endpoint API e confermare che restituisca le risposte previste.

Nella pagina delle impostazioni di AI Assist, usa il pannello di anteprima del chatbot per simulare le domande dei clienti.

• Ricerca prodotto: “Mostrami borse in pelle”
  Comportamento previsto: attiva una chiamata API di ricerca prodotto.
• Tracciamento ordine: “Dov’è il mio ordine #12345?”
  Comportamento previsto: attiva una chiamata API di tracciamento ordine.
• Domanda non correlata: “Che tempo fa oggi?”
  Comportamento previsto: non dovrebbe attivare nessuna chiamata API.

Assicurati che la tua API gestisca situazioni come:

• Nessun prodotto trovato
• Ordine non trovato
• Ritardi o timeout dell’API
• Errori dell’API
• 
  

Ecco alcuni problemi comuni che potresti incontrare durante la configurazione di un’integrazione API.

• Il toggle Status dell’integrazione è disattivato
• Le descrizioni dello schema sono troppo vaghe
• Le istruzioni del Base Prompt non fanno riferimento allo strumento corretto

• Vai su Integration/API e conferma che l’integrazione sia attivata per il tuo agente.
• Controlla le descrizioni dello schema e assicurati che spieghino chiaramente quando usare l’API.
• Aggiungi un’istruzione nel Base Prompt se necessario per guidare AI Assist.

In chat, AI Assist potrebbe rispondere con un messaggio tipo:

“Non sono riuscito a recuperare queste informazioni.”

• L’API non ha restituito risultati corrispondenti
• I parametri della richiesta erano errati
• Problema di autenticazione
• Errore o timeout dell’API

• Testa direttamente l’endpoint API usando Postman o un browser.
• Verifica che gli stessi parametri restituiscano risultati validi.
• Controlla che le credenziali di autenticazione e la API Base URL siano corrette.
• Se non riesci a identificare la causa, contattaci tramite live chat. Il nostro team può controllare la richiesta completa.

Cause possibili:

• Il file dello schema non è accessibile pubblicamente
• Lo schema non è in formato OpenAPI 3.0 valido

• Apri l’URL dello schema in un browser per confermare che sia accessibile.
• Valida lo schema usando editor.swagger.io.

Questo può succedere se AI Assist genera informazioni non presenti nella risposta API.

“Condividi solo le informazioni restituite dall’API.”

Attualmente, le chiamate agli strumenti API non vengono mostrate nel pannello di anteprima nella sezione delle fonti dati.

• AI Assist utilizza le descrizioni nel tuo schema per determinare quando e come chiamare l’API. Descrizioni chiare migliorano l’affidabilità.
• Ogni richiesta API è indipendente. AI Assist non accede direttamente alle risposte API precedenti, ma può fare riferimento ai messaggi già inviati nella conversazione.
• Le risposte API hanno priorità sulle altre fonti di dati. Se i dati dell’API sono disponibili, AI Assist li utilizzerà prioritariamente nelle risposte.
• Le conversazioni lunghe possono essere troncate, impedendo ad AI Assist di fare riferimento ai messaggi precedenti.

• L’API Base URL può essere modificata in qualsiasi momento, mentre il Schema File URL non può essere visualizzato né modificato.
• Lo schema è memorizzato come snapshot. Se aggiorni il file dello schema all’URL sorgente, l’integrazione non si aggiornerà automaticamente.

1. Elimina l’integrazione esistente.
2. Aggiungi nuovamente l’integrazione utilizzando lo schema aggiornato.

• Testa la tua API per accuratezza, latenza e sicurezza.

• Segui le migliori pratiche per autenticazione e crittografia.

• Configura percorsi di escalation in modo che l’agente AI possa trasferire la conversazione a un operatore umano quando necessario.

• Usare le istruzioni del Base Prompt per l’escalation
• Come addestrare AI Assist a trasferire le chat agli operatori umani

Le sezioni seguenti sono destinate agli sviluppatori che devono creare l’endpoint API e lo schema OpenAPI.

• Accettare richieste HTTP (GET o POST)
• Restituire risposte in formato JSON
• Essere pubblicamente accessibile

Lo schema deve seguire il formato OpenAPI 3.0 (YAML o JSON).

• Swagger Editor – per scrivere e visualizzare in anteprima lo schema

• Swagger Validator – per convalidare lo schema

I campi description nel tuo schema aiutano AI Assist a capire quando chiamare l’API e come utilizzarla.

Esempio:

“Usa quando il cliente chiede informazioni sui prodotti, sulla disponibilità in magazzino o vuole sfogliare gli articoli.”

Spiega da dove provengono i valori e come devono essere formattati.

“Estrai la parola chiave dal messaggio del cliente.”

Esempi:

“Se la disponibilità è 0, informa il cliente che l’articolo è esaurito.”
“Se è presente un URL di tracciamento, includilo sempre nella risposta.”

Evita descrizioni vaghe come:

• “L’azione da eseguire”
• “Parola chiave per la ricerca”

• Introduzione a AI Assist
• Modifica del Base Prompt
• Come integrare AI Assist con Shopify
• Come integrare AI Assist con WooCommerce
• Come integrare AI Assist con BigCommerce
• Come integrare AI Assist con Picqer
• Comprendere le fonti di dati di AI Assist
• Distribuire più agenti AI su diversi canali di supporto
• Usare le istruzioni del Base Prompt per l’escalation
• Come addestrare AI Assist a trasferire le chat agli operatori umani