# Azioni API personalizzate: chiama la tua API in chat

> Fai chiamare la tua API HTTP all'agente intoCHAT durante la chat: richiesta e autenticazione, import da cURL, input presi dalla conversazione e test.

Un'azione API personalizzata permette all'agente di chiamare un endpoint HTTP durante la conversazione, per esempio per controllare disponibilità o prezzi aggiornati, e di rispondere in base alla risposta ricevuta. Le azioni si creano nella scheda **Actions** (azioni) dell'agente. Se vuoi che l'agente offra un link invece di chiamare un'API, vedi [Pulsanti personalizzati](/it/docs/custom-buttons).

## Creare un'azione

Fai clic su **Add Action**, oppure su **Import a request** per partire da un comando cURL. L'editor ha quattro passaggi e si salva una sola volta alla fine con **Create action**. Il test è facoltativo ma consigliato.

### 1. The request (la richiesta)

- **Method**: GET, POST, PUT, PATCH o DELETE.
- **HTTPS URL**: l'endpoint. Una query string incollata nell'URL viene spostata nella scheda **Parameters**.
- **Parameters**, **Headers** e **Body** accettano coppie chiave e valore. **Body** è disponibile per tutti i metodi tranne GET e viene inviato come JSON.
- **Collect data inputs for action (optional)**: valori che l'agente ricava dalla conversazione. Ogni input ha un **Name** (lettere, numeri e trattini bassi), un **Type** (Text, Number o Boolean), una **Description** e le opzioni **Required** e **Array**. Fino a 25 input per azione.

Usa un input in qualsiasi punto della richiesta come `{{name}}`: nel percorso dell'URL, in un parametro, in un header o nel body.

```text
GET https://api.example.com/products/{{productId}}/stock
```

L'agente trova il valore nella conversazione o lo chiede al visitatore. Un input **Required** impedisce all'agente di chiamare l'azione prima di avere quel valore. Le variabili usate ma non dichiarate come input vengono tolte dalla richiesta; l'editor ti avvisa e propone **Add them**.

### Autenticazione

| Opzione | Che cosa viene inviato |
| --- | --- |
| **No authentication** | Niente |
| **Bearer token / access token** | Un header `Authorization: Bearer` con il tuo token |
| **API key in a header** | La chiave nell'header che indichi, per esempio `X-API-Key` |
| **API key in the URL** | La chiave come parametro di query con il nome che indichi, per esempio `api_key` |
| **Username and password** | Autenticazione HTTP basic |
| **Custom — I'll set the headers myself** | Ciò che aggiungi nella scheda **Headers** |

### Importare una richiesta

Incolla l'esempio cURL dalla documentazione della tua API, oppure usa "Copy as cURL" su una richiesta negli strumenti di rete del browser. Metodo, URL, parametri, header e body vengono compilati, e la credenziale finisce nel selettore **Authentication**. L'importazione sostituisce la richiesta ma mantiene nome e descrizione. Gli upload multipart (`-F`) vengono saltati e un body in formato form viene importato come campi JSON.

### 2. Try it (prova)

Inserisci valori di prova per gli input e fai clic su **Send test request**. La richiesta viene costruita esattamente come la costruirà l'agente. La **Response Preview** mostra lo stato, il corpo della risposta e l'URL chiamato.

### 3. When the AI should use it (quando usarla)

- **Action Name**: fino a 60 caratteri.
- **When to use**: che cosa fa l'azione, quali dati restituisce ed esempi di domande che devono attivarla. Il modello legge i primi 1.024 caratteri.
- **Server-side action** viene eseguita sui server di intoCHAT ed è l'impostazione predefinita. **Client-side action** viene eseguita nel browser del visitatore; vedi [Azioni lato client](/it/docs/client-actions).
- **Enable this action**: disattiva un'azione senza eliminarla.

### 4. What the AI can see (che cosa vede l'AI)

**Full data access** passa al modello tutta la risposta. **Limited data access** passa solo i campi che selezioni in **Visible**; esegui prima un test per caricare l'elenco dei campi. Se la risposta è un elenco, i campi vengono letti dal primo elemento e il filtro vale per tutti. Finché non selezioni almeno un campo, passa la risposta completa.

## Limiti e sicurezza

- Fino a 25 azioni per agente, compresi i [pulsanti personalizzati](/it/docs/custom-buttons) e le azioni create da [Collega il tuo negozio](/it/docs/connect-your-store).
- L'URL deve puntare a un host pubblico. Localhost, reti private, indirizzi link-local ed endpoint di metadati cloud vengono rifiutati, anche quando un nome host si risolve in uno di questi. L'editor mostra allora "URL points to a blocked or internal host".
- I reindirizzamenti non vengono seguiti. Se il test mostra "This address redirects somewhere else", fai clic su **Use this address**.
- Ogni chiamata scade dopo 30 secondi.
- Le risposte oltre 40.000 caratteri vengono troncate. Con Limited data access restano piccole.
- Le azioni lato server inviano le tue credenziali dai server di intoCHAT, mai attraverso il browser del visitatore.