Uso del passaggio Effettua chiamata API in un agente AI per la messaggistica (legacy)

What's my plan?

Suite

Team, Growth, Professional, Enterprise, or Enterprise Plus

Questo articolo descrive la funzionalità disponibile solo per i clienti che avevano agenti AI in bozza o pubblicati al 2 febbraio 2025. Per informazioni sulla funzionalità equivalente per Agenti AI - Avanzato, consulta Integrazione di altre piattaforme con Agenti AI - Avanzato.

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, illustreremo le procedure necessarie per includere e configurare il passaggio in un agente AI per la messaggistica.

Per una panoramica del passaggio Effettua chiamata API e delle relative regole di configurazione, consulta Tipi di passaggi degli agenti AI: effettua chiamata API.

Questo articolo include le seguenti sezioni:

• Aggiunta del passaggio Effettua chiamata API all'agente AI
• Aggiunta di dettagli API
• Salvataggio di variabili dalla risposta API
• Informazioni sui branch dei passaggi

Aggiunta del passaggio Effettua chiamata API all'agente AI

L’aggiunta del passaggio Effettua chiamata API all’agente AI comporta una serie di compiti distinti.

Le procedure seguenti presuppongono che tu abbia già creato un agente AI per la messaggistica e che tu stia aggiungendo questo passaggio a tale agente.

Nota: se il sistema chiamato non risponde entro 10 secondi, la chiamata viene chiusa automaticamente.

Per aggiungere il passaggio Effettua chiamata API

1. Nel Centro amministrativo, fai clic su AI nella barra laterale, quindi seleziona Agenti AI > Agenti AI.
2. Fai clic su Gestisci agenti AI per la messaggistica.
3. Fai clic sul nome dell’agente AI da modificare.
4. Fai clic sulla scheda Risposte, quindi crea una nuova risposta o aprine una esistente.
5. 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.
6. Nel pannello Configurazione, fai clic su Effettua chiamata API.
7. 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.

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

1. Nel pannello Configurazione, fai clic su Dettagli API.
2. 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.
3. 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.

4. Facoltativamente, seleziona una connessione per autenticare la chiamata API.
   Nota: Devi creare una connessione prima di usarla nel passaggio Effettua chiamata API .
5. 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 authorization oppure x-api-key, vengono automaticamente rifiutati. Se un passaggio Effettua chiamata API viene rifiutato, la conversazione segue il branch Chiamata API non riuscita del passaggio.

6. 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 agente AI di messaggistica può chiedere a un cliente di fornire il numero di un ordine usando il passaggio Chiedi dettagli. L'agente AI 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.	https://domain.com/api/search?input=value Impossibile aggiungere le variabili al dominio/sottodominio
https://maps.googleapis.com/maps/api/place?input=city_name Recupera una posizione per ricerche di parole chiave dall’API dei luoghi di Google.	https://example.com/api/search?key=value Impossibile aggiungere variabili alla chiave della stringa della query

Se una variabile non è valida o è vuota, l'agente AI la ignora durante una conversazione.

Nota: I valori delle variabili non vengono tradotti automaticamente. Tienilo a mente se ricorri alla traduzione automatica nelle conversazioni di messaggistica.

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

1. Nel pannello Configurazione, fai clic su Effettua chiamata API.
2. 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.
3. Fai clic su Salva.
4. 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

Puoi passare le variabili array usando Effettua chiamata API e fornendo l’URL al sistema esterno. Il sistema esterno deve avere un endpoint API. Un endpoint API è un URL in cui l’API riceve richieste e invia risposte, consentendo a due sistemi di interagire. Il rendering delle risposte viene eseguito nel formato JSON (JavaScript Object Notation), come mostrato nell’esempio seguente.

{               
    "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",
	…
    

Nel Centro amministrativo vengono visualizzati solo i primi elementi nella variabile array per visualizzare i dati che vengono restituiti. Ad esempio, nell’output JSON qui sopra, gli elementi 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.

Nota: nella risposta vengono visualizzati solo i primi 280 caratteri del valore di una proprietà.

Gli array JSON annidati possono anche essere salvati come variabili array. Ad esempio, dato il seguente output JSON, 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.

Se la variabile restituita è null, l'elemento non viene visualizzato nella sequenza. Ad esempio, nello scenario seguente supponiamo che il valore della variabile {{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

In questo esempio, viene creata una variabile array usando un endpoint API che restituisce un array di ordini. La matrice degli ordini è specificata dalla proprietà "results" nel frammento di risposta API seguente.

     {
  "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

1. Nel pannello Configurazione, fai clic su Effettua chiamata API.
2. Inserisci ordini per il nome.
3. Nel pannello Configurazione, fai clic su Dettagli API.
4. Fai clic sul menu a discesa Metodo richiesta e seleziona GET.
5. Inserisci l’URL per l’URL endpoint.
6. In Autenticazione, seleziona il metodo di autenticazione.

   Per maggiori informazioni, consulta Creazione di connessioni per l'integrazione con i servizi esterni.

7. Fai clic su Effettua chiamata API.
8. Fai clic su Salva accanto a risultati.

   

9. Dal menu a discesa Valore, seleziona Ordine, quindi Immagine.

   Usa il nome predefinito della variabile (immagine).

10. 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).

    

11. Fai clic su Salva.

Per creare la sequenza dinamica

1. In Creazione bot, fai clic su Aggiungi passaggio in Chiamata API riuscita e seleziona Aggiungi sequenza.
2. Nel pannello Configurazione, fai clic su Converti in messaggio dinamico.
3. Nel menu a discesa Array, fai clic su risultati. Questo è l’array creato sopra.
4. In Titolo, fai clic sul segno più e seleziona results.item.

   Il titolo e la descrizione possono contenere fino a 128 caratteri.

5. In Link pulsante, fai clic sul segno più e seleziona results.image.
6. In Testo pulsante, fai clic sul segno più e seleziona results.status.
7. In Link immagine, fai clic sul segno più e seleziona results.image.
8. Fai clic su Fatto.

   

Ecco un esempio di sequenza dinamica.

Informazioni sui branch dei passaggi

Il passaggio Effettua chiamata API è un passaggio di diramazione. Aggiungendo questo passaggio, l'agente AI fornirà risposte diverse a seconda che la richiesta API sia stata eseguita correttamente o meno.

L’agente AI seguirà il ramo di errore nei seguenti casi:

• L’API restituisce un codice di risposta 400 o 500.
• Una delle variabili salvate è mancante o contiene un valore null.

In tutti gli altri casi, l’agente AI seguirà il ramo di successo.

Se utilizzi il passaggio Effettua chiamata API, accetti che il sistema esterno con cui ti connetti sia un Non-Zendesk Service (come definito nell'Accordo sui servizi principali). Zendesk non gestisce né controlla i Non-Zendesk Services abilitati tramite l’uso della funzione Estensioni di Creazione bot e Zendesk non è responsabile per gli obblighi di conformità legale o normativa all’utente o ai Non-Zendesk Services.