Strumenti

Gli strumenti estendono ciò che Chat può fare durante una conversazione. Un webhook può recuperare dati in tempo reale da un servizio esterno, mentre uno strumento JavaScript può eseguire codice nel browser dell’acquirente ed eseguire un’azione sul tuo storefront.

Nome e descrizione #

Vai su Chat > Tools e clicca su + Add another tool per aprire l’editor dello strumento. Dai allo strumento un nome chiaro e descrivi quando Chat dovrebbe usarlo.

La descrizione funge da istruzione per l’IA. Sii specifico sulla situazione che dovrebbe attivare lo strumento. Ad esempio:

“Quando un cliente chiede informazioni su un ordine, utilizza i dati dell’ordine disponibili in product_data per fornire informazioni sul suo ordine.”

Una descrizione chiara aiuta Chat a utilizzare correttamente lo strumento ed evita che venga chiamato per domande non correlate.

Tipo di strumento #

Scegli Webhook oppure JavaScript nella sezione Type. Webhook chiama una API HTTPS. JavaScript viene eseguito nel browser dell’acquirente.

Costruisci con Ask #

Se non vuoi configurare tu stesso lo strumento, chiedi ad Ask Clerk.io di proporre un webhook o uno strumento JavaScript. Descrivi cosa dovrebbe fare Chat, quindi esamina e conferma il nome, la descrizione, i parametri e la configurazione proposti prima di utilizzarlo.

Webhook #

In Type, seleziona Webhook. Gli strumenti Webhook chiamano la tua HTTP API. Utilizzali quando un servizio può fornire i dati o eseguire l’azione di cui Chat ha bisogno tramite un endpoint.

Parametri #

Definisci i valori di cui Chat ha bisogno prima di poter eseguire lo strumento. Chat raccoglie questi valori dalla conversazione e chiede al visitatore ogni valore richiesto che manca.

Per ogni parametro, definisci:

• Nome — Il nome della variabile utilizzato dall’endpoint o dalla funzione JavaScript.
• Tipo — Il tipo di valore che Chat dovrebbe raccogliere, come testo o numero intero.
• Descrizione — Cosa rappresenta il valore e cosa Chat dovrebbe chiedere al visitatore.

Usa gli stessi nomi dei parametri sia nella tua richiesta che nel codice JavaScript come nell’elenco dei parametri. Ad esempio, un parametro chiamato order_id deve essere letto come order_id nel relativo template o funzione.

Contrassegna un parametro come Required quando lo strumento non può funzionare senza di esso.

Endpoint #

Configura la richiesta HTTP che Chat invia quando viene eseguito uno strumento webhook.

Metodo: Scegli tra GET, POST, PUT o DELETE, a seconda di ciò che richiede la tua API.

URL: Inserisci l’URL completo dell’endpoint. I parametri della query possono essere statici oppure utilizzare i valori raccolti dalla conversazione con {{parameter_name}}. Ad esempio:

https://api.example.com/orders?email={{email}}&id={{order_number}}

Intestazioni personalizzate: Aggiungi eventuali intestazioni richieste dalla tua API, come token di autenticazione o override del content type.

Corpo della richiesta: Per richieste POST e PUT, inserisci il corpo nel formato previsto dalla tua API. Puoi usare anche qui i parametri.

Timeout: Scegli quanto tempo Chat dovrebbe attendere una risposta prima di interrompere la richiesta. Le opzioni disponibili vanno da 3 secondi a 10 minuti.

Salva e testa #

Clicca su Save quando lo strumento è pronto.

Apri Test dalla barra degli strumenti della pagina o dal suo menu delle azioni. Nel popup di test, inserisci valori di esempio per i parametri configurati, esegui il test e ispeziona la risposta. Chiudi il popup per tornare all’editor.

JavaScript #

In Type, seleziona JavaScript. Gli strumenti JavaScript vengono eseguiti nel browser dell’acquirente e possono collegare Chat a funzionalità già esistenti sul tuo storefront, come:

• aggiungere un prodotto al carrello
• leggere il carrello attuale
• applicare un codice sconto
• aprire il checkout
• aprire una guida alle taglie
• salvare un prodotto in una wishlist
• aprire un localizzatore negozi o un flusso click-and-collect

Queste sono azioni personalizzate, non operazioni integrate. È necessario collegare ogni strumento alla funzionalità corrispondente nel tuo storefront.

Parametri #

Definisci i valori di cui Chat ha bisogno prima di poter eseguire lo strumento. Chat raccoglie questi valori dalla conversazione e chiede al visitatore ogni valore richiesto che manca.

Per ogni parametro, definisci:

• Nome — Il nome della variabile utilizzato dalla funzione JavaScript.
• Tipo — Il tipo di valore che Chat dovrebbe raccogliere, come testo o numero intero.
• Descrizione — Cosa rappresenta il valore e cosa Chat dovrebbe chiedere al visitatore.

Usa gli stessi nomi dei parametri sia nella tua richiesta che nel codice JavaScript come nell’elenco dei parametri. Ad esempio, un parametro chiamato order_id deve essere letto come order_id nel relativo template o funzione.

Contrassegna un parametro come Required quando lo strumento non può funzionare senza di esso. Leggi i valori raccolti dall’oggetto args nella tua funzione.

Codice #

Scrivi una funzione asincrona che lo storefront esegue quando Chat chiama lo strumento. L’editor fornisce alla funzione gli argomenti raccolti e il contesto dello storefront.

Usa l’oggetto args per leggere i valori definiti in Parameters. Quindi richiama il codice dello storefront che esegue l’azione, come aggiungere un articolo al carrello o aprire il checkout. Restituisci un risultato chiaro in modo che Chat possa informare il visitatore sul risultato dell’azione.

Il codice JavaScript specifico dipende dal tuo storefront. Assicurati che la funzione gestisca in modo sicuro valori mancanti, non validi o non disponibili.

Salva e testa #

Clicca su Save quando lo strumento è pronto.

Testa gli strumenti JavaScript su uno storefront di test o in anteprima prima di renderli disponibili ai visitatori. Verifica sia l’azione sullo storefront che il messaggio che Chat fornisce dopo il completamento dell’azione.