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
- Apri il bot in Creazione bot.
- Fai clic sull’icona Aggiungi nuovo 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. Queste sono visibili al tuo team mentre i clienti non vedranno le informazioni inserite qui:
- Nome: il nome della chiamata che ne semplifica l’identificazione da parte del team.
- Descrizione (facoltativo): una breve descrizione dell’azione intrapresa dalla chiamata.
- Continua con la procedura descritta in Aggiunta di dettagli API, di seguito.
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.
- Usa il menu a discesa per selezionare un metodo di richiesta:
- GET recupera i dati da un server nella risorsa esterna. Questo è il metodo più usato.
- POST invia i dati per creare o aggiornare una risorsa in un sistema esterno. Se la risorsa esiste già, i dati inviati la modificano.
- PUT invia i dati per aggiornare o creare una risorsa. Se la risorsa esiste già, i dati inviati la sostituiscono.
- 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 ulteriori informazioni, consulta Utilizzo del passaggio Effettua chiamata API in un bot conversazionale. - 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 le connessioni API.
I passaggi Effettua chiamata API che includono un’intestazione correlata all’autenticazione, come
authorization
oppurex-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.json Recupera 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
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"
},
…
Useremo Effettua chiamata API per creare la variabile array e poi useremo 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.
- Se l’opzione non è già selezionata, fai clic sul menu a discesa Metodo richiesta e seleziona GET.
- Inserisci https://run.mocky.io/v3/b6c6180b-924c-407f-852d-9887d9a1641e come URL dell’endpoint.
- In Autenticazione, seleziona Nessuna autenticazione. Se l’endpoint specifico richiede l’autenticazione, seleziona una connessione esistente o creane una nuova. Per maggiori informazioni, consulta Creazione di connessioni API per Creazione bot.
- Fai clic su Effettua chiamata API.
- Fai clic su Salva accanto a risultati.
- Nel 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 (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.
- Aggiungi la risposta ordini al bot.
- Fai clic su Prova bot.
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.
Se l'API ha restituito un codice di risposta pari a 400, 500 o 200 con dati in cui manca una qualsiasi delle variabili, il bot si sposterà in basso nel branch dell'errore