Suite | Team, Growth, Professional, Enterprise, or Enterprise Plus |
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
L’aggiunta del passaggio Effettua chiamata API all’agente AI comporta una serie di compiti distinti.
Per aggiungere il passaggio Effettua chiamata API
- Nel Centro amministrativo, fai clic su
AI nella barra laterale, quindi seleziona Agenti AI > Agenti AI.
- Fai clic su Gestisci agenti AI per la messaggistica.
- Fai clic sul nome dell’agente AI 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
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 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. ![]() |
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, l'agente AI la ignora 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 per l'integrazione con i servizi esterni.
- 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. Aggiungendo questo passaggio, l'agente AI fornirà risposte diverse a seconda che la richiesta API sia stata eseguita correttamente o meno.
- 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.
70 commenti
Leo Alberti
Seconding the request to increase the character limit for variables. Some self-service links I'm trying to provide customers exceed this length, so the limit is quite a blocker.
0
Alex Duffey
We need the character limit to be lifted. 280 is very small. Please look at opening this in the future. We are trying to a return an accessory list of products for one of our products, but the 280 limit stops us from providing that full list.
We tried breaking it up into multiple variables, but the the system requires us to save each one for each new product, which then runs into the 50 mac variable limit.
Please either raise the character limit to at least 1000 or raise the variable limit to at least 200.
1
Jeffrey Porter
Is it possible to include the originating URL for the page on which the chat bot was accessed in an API call? Our use case is that we are installing the chat bot on a video player and each video has a distinct URL. I created a chat bot flow that creates a Zendesk ticket. We'd like to be able to include the URL for the page in the ticket so we know where to go look for a problem. Right now we'd have to ask the user for something and we're guaranteed to get vague answers.
0
Aktie Projeto
Como faço para apagar variáveis que coloquei para teste e agora estão ocupando espaço no meu bot?
0
Yiannis Lamprou
I am trying to get data from hubspot via Make API call.
I am using POST method and i get all fields i want and can turn them to variable.
However the fields ( variables) are coming as numbers. (e.g
"hs_pipeline_stage":"67655766",
)How can i say to ZD to display text according to the variable coming in?
Is there a way to create an array or so besides carousel?
0
이지훈(AI Tester)
I have a similar question to 6336142945306
For example, I want to use users.json to allow end users to retrieve their information using an API.
If a user has a "custom_role_id" value, I can create a flow by saving that value as a variable.
However, if the flow is executed for a user who does not have a "custom_role_id" value, an API error is returned.
In conclusion, even null values should be saved as variables, and when the variable is referenced in the flow, a null value should be returned instead of an error.
Is this possible?
0
Nir Tzezana
Hi,
I have some data I want to add to the API request body, this is data that I already have when the chat window opened (no need to gather it from the user), how can I do that?
0
Fatima Sbeih
Has anyone managed to set this up with Stripe?
0
דורין אברבך
Hey, https://support.zendesk.com/hc/en-us/articles/4572971586586/comments/4614301298458 is there any updates?
about getting information from the user in order to use their input as parameters in API request
0
Javier DM
Este caso que comentas, está justamente mencionado al pie de este artículo, donde pone:
He visto este tipo de situaciones, cuando se quiere utilizar un
null
value como expresión boolean. Por eso la llamada puede ser exitosa (respuesta 200), pero el valor no corresponde a ninguna de las varlables que se han guardado para el flujo, por lo que el paso API fallará.Un ejemplo:
En este caso, cuando el valor sea
null
el paso API va a fallar, por mas que la llamada sea exitosa. Ya que la variable aquí guardada esorganization_id
ynull
no es un valor exista para ese atributo.Espero esta explicación te sea de utilidad. Si precisaras revisar tu caso en mas profundidad, te sugiero por favor dirigirte a support.zendesk.com/hc e iniciar una conversación con el bot para ponerte en contacto con nuestro equipo de soporte.
Saludos y que tengas buena semana!
0
Accedi per lasciare un commento.