Connettori API per dati live del chatbot

Connettori API

I Connettori API consentono al tuo chatbot di chiamare API REST esterne durante una conversazione per recuperare dati in tempo reale. Usali per cercare ordini, controllare l'inventario, verificare account o recuperare informazioni da qualsiasi servizio che espone un'API. Il chatbot raccoglie i dettagli necessari dal visitatore, chiama la tua API, valida la risposta e presenta il risultato in modo conversazionale.

I Connettori API sono disponibili a partire dal piano Standard. Non sono inclusi nei piani Gratuito o Basic.

Aggiungere un Connettore API

Apri il tuo assistente nella dashboard, espandi Impostazioni avanzate sotto le schede principali, seleziona Connettori API e fai clic su Aggiungi Connettore API. I connettori API non sono un Canale o una Funzione. Puoi iniziare da un modello predefinito oppure creare un connettore personalizzato da zero.

Campi di Configurazione

Impostazioni di Base

Field	Description	Required
Nome	Un nome descrittivo per questo connettore (es. "Ricerca Ordine", "Verifica Inventario").	Sì
URL	L'URL endpoint API (es. `https://api.example.com/orders`).	Sì
Metodo HTTP	Metodo HTTP: `GET`, `POST`, `PUT`, `PATCH` o `DELETE`.	Sì (predefinito: GET)
Headers (JSON)	Header HTTP opzionali in formato JSON (es. `{"Authorization": "Bearer abc123", "Content-Type": "application/json"}`). Deve essere un JSON valido.	No
Abilitato	Indica se questo connettore è attivo.	Sì (predefinito: Attivo)

Corpo Richiesta (solo POST/PUT/PATCH)

Field	Description
Tipo Contenuto	Formato del corpo della richiesta: `JSON` o `Form Data`.
Template Corpo	Modello per il corpo della richiesta. Usa segnaposto come `{email}`, `{order_id}` che corrispondono ai campi definiti.

Esempio di template corpo:

{
  "email": "{email}",
  "order_id": "{order_id}"
}

Campi

I campi definiscono quali informazioni il chatbot deve raccogliere dal visitatore prima di chiamare l'API. Ogni campo include:

Property	Description	Required
Nome Campo	L'identificatore del campo (es. `order_id`, `email`). Usato come segnaposto nel corpo della richiesta.	Sì
Tipo	Tipo di dato: `string`, `number`, `email` o `boolean`.	Sì (predefinito: string)
Descrizione (per l'IA)	Spiega all'IA a cosa serve questo campo e come richiederlo al visitatore.	No
Obbligatorio	Indica se il visitatore deve fornire questo campo prima della chiamata all'API.	No

Esempio di campi:

Name	Type	Description	Required
`order_id`	string	Il numero d'ordine del cliente, di solito inizia con ORD-	Sì
`email`	email	L'indirizzo email utilizzato al momento dell'ordine	Sì

Regole di Validazione Risposta

Le regole di validazione verificano che la risposta dell'API corrisponda all'input del visitatore. Questo evita di restituire dati relativi alla persona o all'ordine sbagliato.

Ogni regola include:

Property	Description
Campo Input	Quale campo fornito dal visitatore usare per la convalida (tra i campi definiti).
Percorso Risposta	Percorso del valore nella risposta API (es. `billing.email`, `data.order.status`). Usa la notazione con punto per gli oggetti nidificati.
Confronto	Modalità di confronto: `equals`, `equals (ignore case)`, `contains` o `not empty`.
Messaggio Errore	Messaggio mostrato al visitatore quando la validazione non riesce (es. "L'email non corrisponde ai nostri archivi").

Esempio di validazione:

Input Field	Response Path	Comparison	Error Message
email	billing.email	equals (ignore case)	L'indirizzo email non corrisponde all'ordine. Controlla e riprova.

Prompt

Istruzioni per l'IA su quando e come usare questo connettore. Questo elemento è fondamentale affinché il chatbot sappia quando attivare la chiamata API.

Esempio di prompt:

Use this connector when a customer asks about their order status, shipping 
information, or delivery date. Ask for their order ID and email address before 
making the API call. Present the order status, shipping method, and estimated 
delivery date in a friendly format.

Come Funziona

Il visitatore pone una domanda che corrisponde al prompt del connettore (es. "Dov'è il mio ordine?")
Il chatbot richiede i campi obbligatori (es. ID ordine, email)
Il visitatore fornisce le informazioni
Il chatbot chiama l'API con i dati raccolti
Le regole di validazione vengono verificate rispetto alla risposta
Se la validazione ha successo, il chatbot presenta i dati in formato conversazionale

Concatenare Più Connettori API

Puoi combinare più connettori API per gestire flussi di lavoro complessi. L'IA li concatena automaticamente quando necessario.

Esempio: Autenticazione + Recupero Dati

Connettore 1, "Autentica Cliente": chiama un endpoint di accesso con l'email e la password del visitatore, quindi riceve un token di autenticazione nella risposta.
Connettore 2, "Recupera Dettagli Ordine": usa il token della prima richiesta per chiamare un endpoint API protetto e recuperare i dati dell'ordine.

L'IA gestisce tutto in modo trasparente: riconosce che il secondo connettore richiede i dati del primo, esegue le chiamate nell'ordine corretto e presenta il risultato finale al visitatore, tutto all'interno di un unico flusso di conversazione.

Per configurare questa logica, imposta ciascun connettore in modo indipendente con il proprio endpoint, i campi e il prompt. Nel prompt del secondo connettore, indica che dipende dai dati del primo (es. "Usa il token di autenticazione dal connettore Autentica Cliente per chiamare questo endpoint"). L'IA organizzerà la sequenza automaticamente.

Best Practice

Scrivi prompt chiari: il prompt è il campo più importante, poiché determina quando viene attivato il connettore
Aggiungi regole di validazione: valida sempre i dati sensibili per evitare fughe di informazioni
Usa descrizioni dei campi dettagliate: aiuta l'IA a porre le domande giuste in modo naturale
Esegui prove con risposte API reali: assicurati che il percorso della risposta corrisponda alla struttura effettiva della tua API
Gestisci gli errori in modo adeguato: imposta messaggi di errore chiari in caso di mancata validazione
Usa header di autenticazione: proteggi sempre i tuoi endpoint API con un'adeguata autenticazione