Il passaggio Effettua chiamata API ti consente di configurare una chiamata API in un altro sistema, come un CRM o ERP interno, o di trasmettere i dettagli della conversazione a un endpoint esterno, come Amazon Event Bridge o Google Analytics.
In questo articolo, ti guideremo attraverso le procedure necessarie per includere e configurare il passaggio in un bot conversazionale.
Per una panoramica del passaggio Effettua chiamata API e delle relative regole di configurazione, consulta Tipi di passaggi dei bot: effettua chiamata API.
Questo articolo include le sezioni seguenti:
Aggiunta del passaggio al bot Effettua chiamata API
L’aggiunta del passaggio Effettua chiamata API al bot include una serie di compiti distinti.
Per aggiungere il passaggio Effettua chiamata API
- Nel Centro amministrativo, fai clic su
Canali nella barra laterale, quindi seleziona Agenti AI e automazione > Agenti AI. - Fai clic su Gestisci bot conversazionali.
- Fai clic sul nome del bot da modificare.
- Fai clic sulla scheda Risposte, quindi crea una nuova risposta o aprine una esistente.
- In Creazione bot, fai clic sull’icona Aggiungi passaggio nel punto in cui vuoi inserire il passaggio, alla fine di un branch o tra due passaggi esistenti.
- Nel pannello Configurazione, fai clic su Effettua chiamata API.
- Inserisci le informazioni descrittive per il passaggio.
- Nome: il nome della chiamata che ne semplifica l’identificazione da parte del team.
- Descrizione (facoltativo): una breve descrizione dell’azione intrapresa dalla chiamata.
Queste informazioni non saranno visibili ai clienti.
- Continua con la procedura descritta in Aggiunta di dettagli API.
Aggiunta di dettagli API
Utilizza la sezione Dettagli API per configurare la chiamata HTTP che desideri effettuare, compreso il metodo di richiesta HTTP, la posizione della risorsa esterna e l'aggiunta di intestazioni, se necessario. I passaggi seguenti sono una continuazione della procedura descritta nella sezione precedente.
Per aggiungere i dettagli API
- Nel pannello Configurazione, fai clic su Dettagli API.
- Seleziona un Metodo di richiesta:
- GET recupera una risorsa esterna dal servizio API. Questo è il metodo più usato.
- POST invia i dati per creare una risorsa in un sistema esterno. Se la risorsa esiste già, i dati inviati la modificano.
- PUT invia i dati per aggiornare una risorsa.
- PATCH invia dati per aggiornare una risorsa in un sito esterno. Viene usato per applicare modifiche parziali alla risorsa.
- DELETE rimuove la risorsa nella posizione esterna.
- Inserisci l’URL di un endpoint.
L’URL dell’endpoint è la posizione della risorsa esterna a cui ti stai collegando. L’URL dell’endpoint supporta il protocollo
https://. Puoi includere le variabili nel percorso dell’URL o nei valori della stringa della query. Per maggiori informazioni, consulta Passaggio di variabili in una chiamata API. - Facoltativamente, seleziona una connessione per autenticare la chiamata API.
Nota: Devi creare una connessione prima di usarla nel passaggio Effettua chiamata API .
- Se necessario, inserisci la chiave e il valore di un’intestazione facoltativa. Importante: Non usare intestazioni per l’autenticazione. Usa invece le connessioni API.
I passaggi Effettua chiamata API che includono intestazioni correlate all’autenticazione, come
authorizationoppurex-api-key, vengono automaticamente rifiutati. Se un passaggio Effettua chiamata API viene rifiutato, la conversazione segue il branch Chiamata API non riuscita del passaggio. - Fai clic su Effettua chiamata API per verificare la chiamata API.
Se all’URL o all’intestazione del passaggio vengono aggiunte le variabili, puoi includere dati di test facoltativi nel servizio esterno per verificare se la chiamata API funziona come previsto. Nota che verrà inviata una richiesta HTTP all’URL dell’endpoint configurato.
Passaggio di variabili in una chiamata API
Quando inserisci l’URL di un endpoint per una chiamata API, puoi includere le variabili nel percorso dell’URL o nei valori della stringa della query. Questo ti permette di trasferire i dati della conversazione al sistema esterno.
Ad esempio, un bot di messaggistica può chiedere a un cliente di fornire il numero di un ordine usando il passaggio Chiedi dettagli. Il bot può quindi usare il passaggio Effettua chiamata API per ottenere lo stato di spedizione dell’ordine dal tuo negozio online.
Non puoi utilizzare variabili nel dominio o sottodominio dell’URL di un endpoint. La tabella seguente contiene esempi di valori validi e non validi dell'URL endpoint.
| URL endpoint valido | URL endpoint non valido |
|---|---|
https://myshopify.com/admin/api/orders/order_number.jsonRecupera un ordine specificando l’ID ordine da Shopify. 
|
Impossibile aggiungere le variabili al dominio/sottodominio |
|
Recupera una posizione per ricerche di parole chiave dall’API dei luoghi di Google. |
Impossibile aggiungere variabili alla chiave della stringa della query |
Se una variabile non è valida o è vuota, il bot la salta durante una conversazione.
Salvataggio di variabili dalla risposta API
Dopo aver configurato i dettagli e aver testato la chiamata API, puoi salvare i valori della risposta JSON della chiamata API come variabili. In un passaggio Effettua chiamata API, puoi salvare fino a 12 variabili. Vengono salvati solo i primi 280 caratteri del valore di una variabile.
Per creare una variabile dai dati della risposta
- Nel pannello Configurazione, fai clic su Effettua chiamata API.
- Espandi la finestra di dialogo e identifica i dati del sistema esterno che vuoi convertire in una variabile.
Suggerimento: Passa alla scheda corpo della Risposta per visualizzare la risposta raw ricevuta dal sistema esterno.
- Fai clic su Salva.
- Assegna un nome alla nuova variabile.
I nomi delle variabili devono includere solo lettere minuscole, numeri e trattini bassi.
Passaggio di variabili array in una chiamata API
{
"info": {
"count": 50,
"pages": 2,
"next": "https://mycompany.com/api/orders?page=2",
"prev": null
},
"results": [
{
"id": 1052,
"name": "Alexander Cummings",
“address”: “123 MyStreet”,
"Item": "belt",
"price": "15.00",
"image": "https://mycompany.com/api/orders/avatar/1.jpeg",
…
id, name, address, item, price e image sono tutti visualizzati. Questi dati vengono in genere passati a una sequenza, che tuttavia può visualizzare solo un massimo di 10 elementi.
lastname e firstname possono essere salvati come variabili array separate.
"name":
{
"lastname": "Cummings”,
"firstname": “Alexander"
},
Non puoi modificare l’array o i suoi valori nella configurazione delle sequenza nel Centro amministrativo. Se vuoi modificare dei dati devi eliminare l’array nel Centro amministrativo e crearne uno nuovo.
{{customer.order}} sia vuoto. Il rendering della scheda 1 mostrerà il titolo parziale "Order number” (Numero ordine). Il titolo risultante della scheda 2 è vuoto, quindi la scheda 2 non verrà visualizzata.
Card 1
Title: Order number {{customer.order}}
Description: Here's your order {{product.description}}
Card 2
Title: {{customer.order}}
Description: Here's your order {{product.description}}
Esempio
{
"info": {
"count": 5,
"pages": 1
},
"results": [
{
"createdAt": "July 10, 2023",
"name": "Connie Stokes",
"Shippingaddress": "123 Street, City, State",
"order": {
"Status": "Ordered",
"Image": "https://images.pexels.com/photos/1484808/pexels-photo-1484808.jpeg"
},
"Quantity": 1,
"Price": 45,
"Item": "Shirt",
"id": "1"
},
… Questo esempio usa Effettua chiamata API per creare la variabile array e una sequenza dinamica per mostrare i risultati a un utente finale.
Per creare l’array
- Nel pannello Configurazione, fai clic su Effettua chiamata API.
- Inserisci ordini per il nome.
- Nel pannello Configurazione, fai clic su Dettagli API.
- Fai clic sul menu a discesa Metodo richiesta e seleziona GET.
- Inserisci l’URL per l’URL endpoint.
- In Autenticazione, seleziona il metodo di autenticazione.
Per maggiori informazioni, consulta Creazione di connessioni API per Creazione bot.
- Fai clic su Effettua chiamata API.
- Fai clic su Salva accanto a risultati.
- Dal menu a discesa Valore, seleziona Ordine, quindi Immagine.
Usa il nome predefinito della variabile (immagine).
- Fai clic su Aggiungi elemento e ripeti il passaggio sopra per creare elementi per Stato ordine ed Elemento.
Puoi aggiungere fino a 12 elementi (o coppie chiave-valore).
- Fai clic su Salva.
- In Creazione bot, fai clic su Aggiungi passaggio in Chiamata API riuscita e seleziona Aggiungi sequenza.
- Nel pannello Configurazione, fai clic su Converti in messaggio dinamico.
- Nel menu a discesa Array, fai clic su risultati. Questo è l’array creato sopra.
- In Titolo, fai clic sul segno più e seleziona results.item.
Il titolo e la descrizione possono contenere fino a 128 caratteri.
- In Link pulsante, fai clic sul segno più e seleziona results.image.
- In Testo pulsante, fai clic sul segno più e seleziona results.status.
- In Link immagine, fai clic sul segno più e seleziona results.image.
- Fai clic su Fatto.
Ecco un esempio di sequenza dinamica.
Informazioni sui branch dei passaggi
Il passaggio Effettua chiamata API è un passaggio di diramazione. L'aggiunta di questo passaggio suddivide le risposte del bot in base all'esecuzione dell'API.
- L’API restituisce un codice di risposta 400 o 500.
- L’API restituisce un codice di risposta 200 in cui una delle variabili salvate risulta mancante o ha valore
null.
Il bot si sposterà in basso nel branch per esito positivo in tutti gli altri casi.