> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Outils et webhooks
> Permettre aux assistants d'appeler des outils en conversation et d'envoyer les résultats des appels à vos systèmes via des webhooks
Les assistants peuvent appeler des outils pendant une conversation pour rechercher une information ou effectuer une action. Une fois un appel ou une conversation terminé, Famulor peut transmettre le résultat à vos systèmes via un webhook.
## Outils d'assistant réutilisables
Créez les outils une seule fois sur la page **Tools**, puis attribuez-les sous **Assistant → Settings → Tools** ou ajoutez-les à un flux. Mettre à jour un outil réutilisable met à jour toutes ses attributions.
### Outils API
Les outils API appellent un point de terminaison HTTP pendant une conversation. Définissez :
* le point de terminaison et l'authentification,
* les informations que l'assistant doit recueillir,
* les éventuelles valeurs fixes,
* ce que doit contenir la réponse, et
* si l'appelant doit entendre une courte phrase de progression.
Utilisez des descriptions claires et ne renvoyez que les données nécessaires à la suite de la conversation. La description d'un outil détermine aussi *quand* l'assistant y a recours — énoncez clairement la condition de déclenchement (« utilise ceci quand l'appelant demande des informations sur une commande existante ») plutôt que de décrire uniquement ce que fait l'outil.
| Méthode | Utilisation |
| -------- | ------------------------------------------------------------------------- |
| `GET` | Récupérer des données — une recherche, une vérification de disponibilité |
| `POST` | Créer quelque chose de nouveau — une commande, un ticket, une réservation |
| `PUT` | Remplacer entièrement un enregistrement existant |
| `PATCH` | Mettre à jour des champs spécifiques d'un enregistrement existant |
| `DELETE` | Supprimer quelque chose |
Les requêtes expirent après 10 secondes par défaut (configurable jusqu'à 120), et une réponse de plus de 2 Mo est rejetée — gardez vos points de terminaison rapides et vos réponses courtes. Utilisez une clé API restreinte au moindre privilège plutôt qu'un identifiant maître, et évitez tout détail identifiant le client dans un message d'erreur que l'assistant pourrait relire à voix haute.
Construisez un outil API lorsque la réponse change souvent et que le point de terminaison répond rapidement et de façon fiable. Si l'information change à peine, une [base de connaissances](/fr/assistants/knowledge-base) ou le prompt système est plus économique et ne peut pas échouer en cours d'appel.
**Exemples de configuration**
Chaque valeur recueillie par l'assistant est un paramètre nommé, accompagné d'une description indiquant quoi demander. Les paramètres circulent dans la chaîne de requête pour `GET` et `DELETE`, et dans le corps JSON pour `POST`, `PUT` et `PATCH`. Pour en placer un dans le chemin à la place, écrivez `{{parameter_name}}` dans l'URL du point de terminaison. Définissez la source d'un paramètre sur **Static** pour une valeur fixe que l'assistant n'a jamais à demander, et conservez les identifiants dans **Headers**.
| Modèle | Méthode | Configuration |
| --------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Rechercher par ID | `GET` | Point de terminaison `.../orders/{{order_number}}`, avec `order_number` comme paramètre recueilli par l'assistant |
| Créer quelque chose | `POST` | Point de terminaison `.../appointments`, avec `date` et `service` comme paramètres — envoyés dans le corps JSON |
| Vérifier avant de continuer | `GET` | Point de terminaison `.../customers/lookup`, avec `phone` et `email` comme paramètres — envoyés comme valeurs de requête |
| Notifier uniquement | `POST` | Point de terminaison `.../notify` avec uniquement des paramètres statiques ; l'assistant confirme simplement avoir transmis le message |
L'assistant lit la réponse et répond avec ses propres mots — renvoyez donc des champs courts et clairement nommés (`ship_date`, `confirmed_time`) plutôt qu'un objet profondément imbriqué qu'il devrait interpréter.
### Connecteur d'agent Perplexity
Ouvrez **Tools → Agent Connectors**, choisissez **Perplexity AI**, et collez votre propre clé API. Sélectionnez **Load models** pour valider la clé et récupérer les modèles actuellement disponibles pour votre compte. Le même sélecteur de modèle est ensuite disponible dans **Edit** et recharge le catalogue à l'aide de la clé stockée en toute sécurité. Vous pouvez ajouter un prompt système facultatif et ajuster la température (par défaut `0.2`), le Top P (`0.9`), la pénalité de présence (`0`) et la pénalité de fréquence (`1`). Le nombre maximal de jetons est vide par défaut et n'est envoyé dans les requêtes qu'une fois défini. Le prompt système contrôle le ton, la langue, le style et le format de réponse ; l'assistant fournit toujours la demande de recherche complète au moment de l'exécution. La clé enregistrée est masquée et n'est jamais renvoyée par l'API des outils.
### Serveurs MCP externes
Connectez un serveur MCP en saisissant son URL et, si nécessaire, ses informations d'authentification. Vous pouvez autoriser tous les outils proposés ou sélectionner uniquement ceux qu'un assistant peut utiliser. Utilisez cette option lorsque l'autre partie expose déjà tout un ensemble d'outils MCP — une seule connexion apporte tous les outils proposés ; pour un simple point de terminaison HTTP, un outil API classique comme ci-dessus est généralement plus simple.
Une URL se terminant par `/mcp` est traitée comme du Streamable HTTP, et une URL se terminant par `/sse` comme du SSE classique ; toute autre URL essaie d'abord le Streamable HTTP, puis se replie sur le SSE. L'authentification peut être **none**, un **static header or bearer token**, ou **OAuth** — lorsque le serveur prend en charge OAuth, Famulor exécute le parcours de connexion et stocke le jeton obtenu.
La liste **Installed** affiche le résultat de la dernière exécution et signale les connexions nécessitant une intervention. Si OAuth expire, choisissez **Reauthorize** sur l'outil existant. Le parcours de connexion répare cet outil sur place, ce qui préserve les attributions, les outils autorisés, les paramètres et l'historique d'exécution.
Pour chaque outil sélectionné, **Execution behavior** permet de contrôler l'annulation, les appels simultanés et les mises à jour de progression parlées. Une annulation ne peut pas défaire une action déjà terminée par le service externe.
Ne connectez que des services de confiance. Leurs descriptions d'outils, résultats et messages de progression peuvent influencer la conversation.
### Outils intégrés
Les outils intégrés couvrent des actions courantes telles que le transfert d'appel, le transfert vers un autre assistant, les SMS, les e-mails, la vérification des horaires d'ouverture, les rappels, la saisie au clavier, la collecte sécurisée de carte de paiement, les variables et la fin d'appel.
## Gérer les outils via l'API
Utilisez l'API publique pour automatiser la gestion des outils :
* `GET /api/v1/tools` et `POST /api/v1/tools`
* `POST /api/v1/tools/perplexity/models` pour lister les modèles disponibles avec une clé API fournie ou l'identifiant d'un connecteur existant
* `GET /api/v1/tools/{id}`, `PATCH /api/v1/tools/{id}` et `DELETE /api/v1/tools/{id}`
* `POST /api/v1/tools/{id}/reauthorize` pour obtenir une URL de connexion navigateur de courte durée pour un outil MCP OAuth existant
* `GET /api/v1/assistants/{id}/tools` et `PUT /api/v1/assistants/{id}/tools`
* `GET /api/v1/assistants/{id}/automations`, `POST /api/v1/assistants/{id}/automations` et `DELETE /api/v1/assistants/{id}/automations/{automationId}`
Le [point de terminaison MCP](/fr/api/mcp) connecté propose des opérations d'outil d'assistant équivalentes, notamment `reauthorize_tool` et `list_perplexity_models`. Les réponses de liste d'outils incluent l'état de connexion sans secret et le résultat de la dernière exécution. Les valeurs d'authentification secrètes sont masquées après leur enregistrement.
Pour une [automatisation](/fr/automations/overview) que l'assistant doit pouvoir appeler pendant une conversation, utilisez le point de terminaison d'automatisation de l'assistant ou l'outil MCP `create_assistant_automation`. Décrivez précisément quand elle doit s'exécuter. La même attribution est disponible dans les conversations vocales, le chat web, la messagerie et l'e-mail. La plateforme crée un brouillon de workflow et connecte l'outil nécessaire en toute sécurité, sans renvoyer d'identifiants. Construisez ses étapes, renvoyez un résultat concis adapté à une réponse orale ou écrite, puis passez l'automatisation en Live une fois prête ; la mettre en pause désactive aussi l'outil appelable partout. Ces outils générés apparaissent comme gérés par l'automatisation et ne peuvent être modifiés ou déconnectés que depuis les paramètres de l'assistant. Les nouvelles tentatives au sein d'une conversation réutilisent la même exécution et la même réponse, sans répéter la facturation ni les effets de bord.
## Recevoir les résultats d'appel par webhook
Lorsqu'un appel se termine, Famulor envoie son résultat à l'URL de webhook configurée sur l'assistant (**Settings → Automations → Call completed**). Cette URL n'est pas signée et appartient à cet assistant uniquement. Les réglages de livraison par assistant — délai d'expiration, nombre de nouvelles tentatives et envoi de test — se trouvent dans [Webhooks post-appel](/fr/assistants/webhooks).
Les fils e-mail réutilisent la même URL d'assistant : une fois que l'assistant a répondu, Famulor y livre un événement `conversation.ended` contenant la transcription du fil et son analyse. Telegram, Slack et les autres connecteurs de messagerie disposent en revanche de leur propre **Conversation ended webhook URL**, définie par connecteur — voir [Canaux de messagerie](/fr/channels/messaging).
La signature fonctionne différemment pour le **webhook de variables** entrant — l'URL par assistant que Famulor appelle au début d'un appel entrant pour enrichir les variables. Cette requête porte une signature HMAC-SHA256 ; voir [Variables personnalisées](/fr/assistants/variables#webhook-de-variables-entrant).
### `call.completed`
L'événement inclut les informations d'appel destinées au client : assistant, sens, statut, durée, horodatages, transcription, variables de flux collectées, contexte de campagne et liens d'enregistrement disponibles.
Si l'appel ne peut pas aboutir, le payload inclut un objet `failure` indépendant du fournisseur, avec un code stable, un message adapté au client, un conseil de nouvelle tentative et une action suggérée. Construisez votre logique de reprise à partir de cet objet plutôt qu'à partir de détails spécifiques à l'infrastructure.
Renvoyez rapidement une réponse `2xx` de succès. Effectuez les traitements plus longs après avoir accusé réception du webhook.
## Interroger au lieu de recevoir un webhook
Vous pouvez récupérer le même résultat d'appel avec `GET /api/v1/calls`, `GET /api/v1/calls/{id}`, ou les outils d'historique d'appels dans [MCP](/fr/api/mcp). Un appel nouvellement créé renvoie d'abord son statut actuel ; interrogez-le jusqu'à ce qu'il atteigne un état final.