Lo strumento di creazione integrazione è un potente strumento senza codice che ti consente di connettere il tuo agenti AI a qualsiasi API o origine dati senza competenze tecniche o di programmazione estese. Personalizza le tue esperienze di chat e migliora le soluzioni automatizzate con contenuto dinamico.
Immagina un agenti AI in grado di accedere senza problemi alle informazioni sui clienti dal tuo sistema di back office, recuperare dati da qualsiasi altra origine dati esterna o interagire con applicazioni di terzi, il tutto senza dover scrivere una singola riga di codice.
Grazie alle funzionalità contenuto dinamico , lo strumento di creazione integrazioni consente il recupero, l’analisi e la trasformazione dei dati in tempo reale, consentendo agenti AI di fornire risposte, consigli e soluzioni personalizzati in base alle esigenze dei singoli utenti.
Con la sua interfaccia intuitiva, le funzioni intuitive e le funzionalità senza codice, lo strumento di creazione dell’integrazione offre piena flessibilità e personalizzazione senza la necessità di conoscenze tecniche approfondite.
In questo articolo, esploreremo le funzionalità e i vantaggi chiave dello strumento di creazione integrazione, insieme a una guida dettagliata su come sfruttarne le capacità per connettere il tuo agenti AI a qualsiasi API o origine dati.
Per cominciare
Per accedere allo strumento di creazione integrazioni, fai clic su "Integrazioni API" nel menu di navigazione laterale. Verrà visualizzato un elenco di riepilogo in cui tutte le integrazioni future saranno elencate e accessibili. Inizialmente, inizierai senza integrazioni API o con un esempio di integrazione API, a seconda del percorso di onboarding.
Per creare una nuova integrazione, fai clic su "Aggiungi integrazione" nell'angolo in alto a destra.
Fornisci un nome per l’integrazione,
Aggiungi una breve descrizione con contesto aggiuntivo.
Al termine, fai clic su “Salva” per procedere alla pagina di configurazione dell’integrazione.
Se non vedi le integrazioni API nella navigazione laterale, molto probabilmente significa che non sei un amministratore client. Al momento, l’accesso allo strumento di creazione integrazioni è limitato agli amministratori client. In questo caso, contatta il tuo CSM per discutere dei tuoi diritti di accesso.
Se preferisci imparare con input video e audio, abbiamo un video introduttivo di un membro del nostro team tecnico personalizzato, Chloe.
Parametri della richiesta
Per iniziare, devi configurare i parametri di richiesta necessari per garantire una risposta corretta dall’API. Questi parametri di richiesta contengono informazioni derivate dalla conversazione e servono a definire le specifiche della richiesta API. Ad esempio, se intendi recuperare particolari informazioni utente da visualizzare durante la conversazione, diventa fondamentale includere l’ID utente come parte della richiesta. Ciò garantisce che la risposta API contenga dati rilevanti per l’utente o il visitatore corrente impegnato nella chat.
Di seguito è riportato un esempio di parametro di richiesta configurato.
Oltre a specificare la chiave e il tipo di parametro della richiesta, hai la possibilità di impostare un valore di test. Si consiglia vivamente di farlo, in quanto questo valore di test verrà usato durante la configurazione quando si usa la funzionalità di test nell’angolo in alto a destra. Durante una conversazione effettiva, il valore verrà passato all'integrazione API prima di effettuare la richiesta. Tuttavia, poiché il contesto della conversazione attuale non è disponibile, è necessario impostare un valore di test per eseguire correttamente una chiamata API.
La casella di spunta "obbligatorio" consente di determinare se il parametro di richiesta è facoltativo o deve essere raccolto prima di chiamare le integrazioni API nella conversazione, se non è già stato salvato nella sessione.
L’inclusione dei parametri di richiesta dipende dai requisiti specifici dell’API chiamata. Per alcune API, i parametri della richiesta vengono aggiunti all’URL, mentre per altre sono inclusi nelle intestazioni o nel corpo della richiesta. Consulta la documentazione API per determinare dove includere il parametro di richiesta. Una volta identificato, puoi aggiungere il parametro di richiesta all’URL, all’intestazione o al corpo facendo semplicemente riferimento alla chiave racchiusa tra parentesi graffe doppie: {{userID}}.
Ambienti
Una volta aggiunto il parametro di richiesta, la configurazione principale per la chiamata API può essere eseguita nella sezione ambiente. Accanto al nome dell’ambiente visualizzato durante il test di integrazione o quando vi si fa riferimento nello strumento di creazione dialoghi, devi scegliere il metodo, l’URL e il tipo di autorizzazione in base alla documentazione API sottostante.
Tipi di autorizzazione
Offriamo i seguenti tipi di autorizzazione:
| Tipo di autorizzazione | Descrizione | Esempio |
| Chiave API | Una semplice chiave API che deve essere fornita dal proprietario dell’API. |  |
| Token al portatore | Un altro token che deve essere fornito dal proprietario dell’API. |  |
| Autenticazione di base | Per l’autenticazione con l’API vengono usati un nome utente e una password. |  |
| OAuth 2.0 | Sono necessarie diverse informazioni di autenticazione in base al tipo di concessione |  |
| Personalizzate | Autorizzazione tramite token di scadenza | Consulta Uso dell’autorizzazione personalizzata con lo strumento di creazione integrazioni. |
Ricorda di includere il token di autenticazione nella richiesta aggiungendolo come {{apiToken}} alle intestazioni per tutti i tipi di autorizzazione (tranne nessuna autorizzazione). Dai un’occhiata alla sezione dell’intestazione per un esempio.
Intestazioni
Le intestazioni contengono informazioni aggiuntive sulla richiesta o sul client e il server che comunicano tra loro. Sono coppie chiave-valore incluse nella sezione dell’intestazione della richiesta. Alcune intestazioni di uso comune includono:
- Tipo di contenuto: Indica il formato dei dati nel corpo della richiesta (ad esempio, JSON, XML, dati del modulo).
- Autorizzazione: Fornisce credenziali o token per autenticare il client che effettua la richiesta.
- Utente-Agente: Specifica lo user agent che avvia la richiesta, in genere il browser web o l’applicazione client.
- Accetta: Informa il server sui formati di risposta accettati dal client.
- Controllo cache: Definisce le direttive di memorizzazione nella cache per il server o le cache degli intermediari.
- X-Richiesto-Con: Identifica il tipo di richiesta (ad esempio, XMLHttpRequest, API di recupero) effettuata dal client.
Corpo
Il corpo di una richiesta API contiene i dati inviati all’API. In genere viene usato nelle richieste che richiedono l'immissione di dati per l'elaborazione o la manipolazione dei dati sul lato API. Il corpo può contenere vari formati, come JSON, XML, testo normale o dati dei moduli, a seconda dell’API e dell’endpoint specifico chiamato. Nel nostro caso, finora assistenza solo JSON.
Gestione degli ambienti
Per affrontare le sfide legate alla gestione degli ambienti sandbox e di produzione per le API, abbiamo incorporato il concetto di ambienti nello strumento di creazione integrazione. Oltre all’ambiente principale predefinito che viene creato automaticamente durante la configurazione di un’integrazione, hai la possibilità di includere altri ambienti.
Questi ambienti aggiuntivi ti consentono di personalizzare l’URL, i dettagli di autenticazione, le intestazioni e il corpo delle richieste, consentendoti di scegliere come target ambienti sandbox o di produzione specifici all’interno della tua API.
Per creare un nuovo ambiente, fai clic sul pulsante "+" accanto alla sezione Ambiente. Se vuoi replicare un ambiente esistente, posiziona il cursore del mouse su di esso e scegli l’opzione “duplica” dal menu a tre punti. Tieni presente che un solo ambiente può essere impostato come predefinito, che verrà posizionato in cima all’elenco e selezionato automaticamente per primo nello strumento di creazione dialoghi (a meno che non venga modificato intenzionalmente).
Se un ambiente non è utilizzato da alcun agente AI ed è l’unico ambiente o l’ambiente predefinito, può essere eliminato. Per modificare le impostazioni predefinite, puoi selezionare facilmente l’opzione appropriata dal menu a tre punti.
Funzionalità di prova
Una volta completata la configurazione della richiesta API, è utile verificare se tutte le configurazioni sono state eseguite correttamente. Per facilitare questo processo, lo strumento di creazione integrazione offre una comoda funzionalità di test nell’angolo in alto a destra.
Il pulsante di test è facilmente identificabile dall’etichetta “Test” seguita dal nome dell’ambiente predefinito. Facendo clic su di essa, lo strumento di creazione integrazioni avvia una richiesta all’API usando le informazioni fornite nelle sezioni dei parametri della richiesta e dell’ambiente. La risposta ricevuta dall’API viene quindi visualizzata nella sezione Test integrazione sul lato destro dell’interfaccia. Se vuoi testare l’API usando i dettagli della richiesta da un altro ambiente, seleziona l’ambiente desiderato dal menu a discesa all’interno della funzionalità di test e fai di nuovo clic sul pulsante di test.
Contenuto della risposta
Nella sezione Test integrazione, lo strumento di creazione integrazioni presenta la risposta ottenuta dall’API. Il contenuto della risposta è organizzato nei seguenti oggetti:
| Oggetti | contenuti | Esempio |
| statusCode | I codici di stato della risposta HTTP indicano se una specifica richiesta HTTP è stata completata correttamente. Ulteriori informazioni. | "statusCode": 200 |
| dati | L’oggetto dati mostra i dati pertinenti dell’API in caso di richiesta riuscita. Tuttavia, se la richiesta non va a buon fine, fornisce ulteriori informazioni in base ai codici di stato corrispondenti. |
"data": { "name": "Germania", "capital": "Berlino", "regione": "Europa", "popolazione": 83240525, "area": 357114 } |
| requestParameters | All’interno dell’oggetto requestParameters, lo strumento di creazione integrazioni mostra i parametri della richiesta insieme ai valori di test associati usati per richiamare l’API. |
"requestParameters": { "country": "de"} |
Prima di usare nuovamente la funzionalità di test per esaminare l’integrazione con eventuali configurazioni modificate, assicurati di salvare l’integrazione.
Scenari
Ogni integrazione appena creata include tre scenari preconfigurati. Sebbene due di questi scenari possano essere personalizzati o eliminati in base alle tue esigenze, il terzo scenario, denominato "Riserva", non può essere modificato. Questo scenario di "riserva" funge da opzione di fallback principale nel caso in cui nessuno degli scenari precedenti venga attivato.
| Scenario | Query predefinita | Descrizione |
| Operazione riuscita | statusCode >= 200 e statusCode < 300 | Lo scenario che dovrebbe acquisire il percorso preferito/felice se statusCode è compreso tra 200 e 300. |
| Errore | statusCode < 200 o statusCode >= 300 | Lo scenario che dovrebbe acquisire il percorso non riuscito se statusCode è al di fuori di 2XX. |
| Fallback | - | Scenario di fallback per attivare sempre almeno uno scenario. |
Gli scenari sono equivalenti con i diversi rami seguiti dalla conversazione nel dialogo quando viene attivata l’integrazione API.
Query scenario
È possibile attivare un solo scenario per ciascuna integrazione API. La logica per determinare quale scenario viene attivato durante una conversazione si basa sulle query scenario e sull’ordine in cui gli scenari sono definiti.
Le query scenario rappresentano le condizioni che devono essere soddisfatte per attivare uno scenario specifico. Per determinare se una condizione è vera, lo strumento di creazione integrazioni esamina la query scenario e i dati contenuti nella risposta API. I campi dati più usati includono statusCodes, dati specifici dell’API all’interno dell’oggetto dati della risposta API ed eventualmente anche valori dei parametri della richiesta.
La query dello scenario predefinito dello scenario Operazione riuscita richiede che lo statusCode della risposta API sia compreso tra 200 e 300. Se questa condizione viene soddisfatta, verrà attivato lo scenario Operazione riuscita.
Poiché le query degli scenari predefiniti possono essere modificate e possono essere aggiunti nuovi scenari, è possibile che più query di scenari provenienti da scenari diversi siano vere in base alla risposta API. In questi casi, l’ordine degli scenari determina quale scenario verrà attivato.
Per fornire un feedback visivo, abbiamo implementato una funzione che indica quale scenario verrebbe attivato in base alla risposta API corrente. Identifica anche gli scenari che verrebbero teoricamente attivati ma che in realtà non vengono attivati a causa dell’attivazione di uno scenario di ordine superiore. Inoltre, evidenzia gli scenari che non verrebbero attivati perché le relative condizioni non sono soddisfatte.
| I criteri corrispondono | Visualizzazione | Descrizione |
| I criteri corrispondono per primi in ordine |  |
Lo scenario evidenziato da un punto fisso blu rappresenta lo scenario che verrà attivato. |
| I criteri non corrispondono |  |
Gli scenari evidenziati da un punto vuoto non verranno attivati. |
| I criteri corrispondono ma non sono i primi in ordine |  |
Gli scenari rappresentati da un punto pieno grigio verrebbero attivati solo in teoria. |
Per modificare l’ordine degli scenari, fai clic su uno scenario e riordina l’ordine trascinandolo. Ad eccezione dello scenario di fallback, che rimane sempre nell’ultima posizione, puoi modificare l’ordine in base alle tue preferenze.
Parametri di sessione
Quando configuri ogni scenario, hai la possibilità di migliorare la conversazione con vari punti dati dai tuoi sistemi di backend. Puoi specificare i dati desiderati affinché siano accessibili per ogni scenario trasformando e memorizzando le informazioni pertinenti dalla risposta API in parametri di sessione. Questi parametri di sessione possono quindi essere utilizzati nel processo di creazione del dialogo per presentare informazioni ai visitatori o per mappare il workflow sottostante.
Un parametro di sessione è definito da una coppia chiave-valore. La chiave funge da riferimento nello strumento di creazione dialoghi, mentre la query viene usata per trasformare ed estrarre dati specifici dalla risposta API per salvare il valore. Lo strumento di creazione integrazioni fornisce feedback in tempo reale su come il valore salvato, in base alla risposta corrente, apparirà nel campo del valore della risposta.
Nell’immagine qui sopra, la chiave del parametro di sessione è definita come “maiuscola” e può essere referenziata nello strumento di creazione dialoghi usando le parentesi graffe - {{capital}}. La query determina quali dati devono essere trasformati e salvati come valore per il parametro di sessione. In questo caso, estrae il contenuto dal campo "capitale" all'interno dell'oggetto dati della risposta API.
Linguaggio query - JSONata
JSONata funge da linguaggio di query sia per le query a livello di scenario che per le query a livello di parametro di sessione. È progettato in base al principio che le query semplici devono essere facili da scrivere, rendendole accessibili sia ai professionisti esperti che ai non esperti di tecnologia. JSONata presenta una curva di apprendimento poco profonda, che consente di padroneggiarlo rapidamente. Con JSONata, puoi eseguire funzioni di base, trasformare le date e persino unire diversi punti dati.
JSONata è un linguaggio di query e trasformazione documentato pubblicamente e la documentazione è disponibile qui.
Avvertenza sulla traduzione: questo articolo è stato tradotto usando un software di traduzione automatizzata per fornire una comprensione di base del contenuto. È stato fatto tutto il possibile per fornire una traduzione accurata, tuttavia Zendesk non garantisce l'accuratezza della traduzione.
Per qualsiasi dubbio sull'accuratezza delle informazioni contenute nell'articolo tradotto, fai riferimento alla versione inglese dell'articolo come versione ufficiale.