Strumenti

Gli strumenti estendono ciò che Chat può fare durante una conversazione. Un webhook può recuperare dati live da un servizio esterno, mentre uno strumento JavaScript può eseguire codice nel browser del cliente e compiere un’azione sul tuo storefront.

Nome e Descrizione #

Vai a 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, usa i dati dell’ordine disponibili in product_data per fornire dettagli sul loro ordine.”

Una descrizione chiara aiuta Chat a usare correttamente lo strumento ed evitare chiamate non pertinenti.

Build with 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 rivedi e conferma il nome, la descrizione, i parametri e la configurazione proposti prima di utilizzarlo.

Webhooks #

In Type, seleziona Webhook. Gli strumenti webhook chiamano la tua API HTTP. Usali quando un servizio può fornire i dati o compiere l’azione richiesta da Chat 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 mancante.

Per ogni parametro, definisci:

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

Segna 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.

Method: Scegli GET, POST, PUT o DELETE, a seconda di ciò richiesto dalla tua API.

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

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

Request body: Per le richieste POST e PUT, inserisci il body nel formato previsto dalla tua API. Puoi usare qui anche i parametri.

Custom headers: Aggiungi eventuali header richiesti dalla tua API, come token di autenticazione o override del content type.

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

Salva e testa #

Quando lo strumento è pronto, clicca su Save o Save & Close.

Usa la sezione Test in fondo all’editor. Inserisci i valori dei parametri e clicca su Test request per verificare la connessione.

JavaScript #

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

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

Queste sono azioni personalizzate, non operazioni predefinite. Ogni strumento deve essere collegato alla rispettiva funzione presente sul 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 mancante.

Per ogni parametro, definisci:

• Name — Il nome della variabile usato dalla funzione JavaScript.
• Type — Il tipo di valore che Chat dovrebbe raccogliere, come testo o numero intero.
• Description — Cosa rappresenta il valore e cosa Chat dovrebbe chiedere al visitatore.

Segna 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 viene eseguita sullo storefront quando Chat richiama 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. Poi chiama il codice dello storefront che realizza l’azione, come aggiungere un articolo al carrello o aprire il checkout. Restituisci un risultato chiaro, così Chat potrà informare il visitatore sull’esito dell’azione.

Il JavaScript esatto dipende dal tuo storefront. Assicurati che la funzione gestisca correttamente valori assenti, non validi o indisponibili.

Salva e testa #

Quando lo strumento è pronto, clicca su Save o Save & Close.

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