# Actions API personnalisées : appeler votre API

> Laissez votre agent intoCHAT appeler votre API HTTP pendant le chat : requête et authentification, import cURL, entrées tirées de la conversation et test.

Une action API personnalisée permet à l'agent d'appeler un point de terminaison HTTP pendant la conversation, par exemple pour vérifier un stock ou un prix à jour, et de répondre à partir du résultat. Les actions se créent dans l'onglet **Actions** de votre agent. Pour que l'agent propose un lien au lieu d'appeler une API, voir [Boutons personnalisés](/fr/docs/custom-buttons).

## Créer une action

Cliquez sur **Add Action**, ou sur **Import a request** pour partir d'une commande cURL. L'éditeur comporte quatre étapes et l'on enregistre une seule fois à la fin avec **Create action**. Le test est facultatif mais recommandé.

### 1. The request (la requête)

- **Method** : GET, POST, PUT, PATCH ou DELETE.
- **HTTPS URL** : le point de terminaison. Une chaîne de requête collée dans l'URL est déplacée vers l'onglet **Parameters**.
- **Parameters**, **Headers** et **Body** acceptent des paires clé et valeur. **Body** est disponible pour toutes les méthodes sauf GET et est envoyé en JSON.
- **Collect data inputs for action (optional)** : des valeurs que l'agent tire de la conversation. Chaque entrée a un **Name** (lettres, chiffres et tirets bas), un **Type** (Text, Number ou Boolean), une **Description** et les options **Required** et **Array**. Jusqu'à 25 entrées par action.

Utilisez une entrée n'importe où dans la requête sous la forme `{{name}}` : dans le chemin de l'URL, un paramètre, un en-tête ou le corps.

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

L'agent trouve la valeur dans la conversation ou la demande au visiteur. Une entrée **Required** empêche l'agent d'appeler l'action avant d'avoir cette valeur. Les variables utilisées mais non déclarées comme entrées sont retirées de la requête ; l'éditeur vous prévient et propose **Add them**.

### Authentification

| Option | Ce qui est envoyé |
| --- | --- |
| **No authentication** | Rien |
| **Bearer token / access token** | Un en-tête `Authorization: Bearer` avec votre jeton |
| **API key in a header** | Votre clé dans l'en-tête que vous nommez, par exemple `X-API-Key` |
| **API key in the URL** | Votre clé comme paramètre de requête que vous nommez, par exemple `api_key` |
| **Username and password** | Authentification HTTP basic |
| **Custom — I'll set the headers myself** | Ce que vous ajoutez dans l'onglet **Headers** |

### Importer une requête

Collez l'exemple cURL de la documentation de votre API, ou utilisez « Copy as cURL » sur une requête dans les outils réseau de votre navigateur. Méthode, URL, paramètres, en-têtes et corps sont remplis, et l'identifiant est placé dans le sélecteur **Authentication**. L'import remplace la requête mais conserve le nom et la description. Les envois multipart (`-F`) sont ignorés et un corps encodé en formulaire est importé sous forme de champs JSON.

### 2. Try it (tester)

Saisissez des valeurs de test pour les entrées et cliquez sur **Send test request**. La requête est construite exactement comme l'agent la construira. La **Response Preview** affiche le statut, le corps de la réponse et l'URL appelée.

### 3. When the AI should use it (quand l'utiliser)

- **Action Name** : jusqu'à 60 caractères.
- **When to use** : ce que fait l'action, les données qu'elle renvoie et des exemples de questions qui doivent la déclencher. Le modèle lit les 1 024 premiers caractères.
- **Server-side action** s'exécute sur les serveurs d'intoCHAT et c'est le réglage par défaut. **Client-side action** s'exécute dans le navigateur du visiteur ; voir [Actions côté client](/fr/docs/client-actions).
- **Enable this action** : désactive une action sans la supprimer.

### 4. What the AI can see (ce que l'IA voit)

**Full data access** transmet toute la réponse au modèle. **Limited data access** ne transmet que les champs cochés sous **Visible** ; lancez d'abord un test pour charger la liste des champs. Pour une réponse en liste, les champs viennent du premier élément et le filtre s'applique à chaque élément. Tant qu'aucun champ n'est coché, la réponse complète est transmise.

## Limites et sécurité

- Jusqu'à 25 actions par agent, y compris les [boutons personnalisés](/fr/docs/custom-buttons) et les actions créées par [Connecter votre boutique](/fr/docs/connect-your-store).
- L'URL doit viser un hôte public. Localhost, réseaux privés, adresses link-local et points de métadonnées cloud sont refusés, même quand un nom d'hôte pointe vers l'une de ces adresses. L'éditeur affiche alors « URL points to a blocked or internal host ».
- Les redirections ne sont pas suivies. Si le test affiche « This address redirects somewhere else », cliquez sur **Use this address**.
- Chaque appel expire au bout de 30 secondes.
- Les réponses de plus de 40 000 caractères sont tronquées. Limited data access permet de les garder courtes.
- Les actions côté serveur envoient vos identifiants depuis les serveurs d'intoCHAT, jamais par le navigateur du visiteur.