API

Outils personnalisés

Laissez l'IA appeler votre API en pleine conversation

Vue d'ensemble

Un outil personnalisé est un endpoint à vous que l'agent peut appeler pendant qu'il parle à un client : consulter un crédit par numéro d'identité, vérifier le stock, ouvrir un ticket. Vous décrivez quand il s'applique et de quels paramètres il a besoin ; l'IA décide quand l'appeler, remplit les paramètres avec ce qu'a dit le client et répond avec ce que votre API a renvoyé. Jusqu'à 15 outils par agent.

Définition

Chaque outil est une entrée avec ces champs :

`name`	Nom technique avec lequel l'IA l'appelle : lettres, chiffres et tiret bas (consultar_credito).
`description`	Quand l'utiliser et ce qu'il renvoie. C'est ce que l'IA lit pour décider ; rédigez-la comme une instruction (« Consulte un crédit par numéro d'identité ; renvoie le solde et les échéances »).
`parameters`	Liste de {name, type (string \| number \| boolean \| enum), description, required, enum_values}. L'IA les remplit avec ce qu'a dit le client.
`method + endpoint`	GET, POST, PUT ou DELETE et l'URL complète.
`auth`	NONE, BEARER (Authorization: Bearer <token>), API_KEY (nom et valeur d'en-tête de votre choix) ou BASIC (utilisateur et mot de passe).
`headers`	En-têtes supplémentaires envoyés à chaque appel.
`body_template`	Modèle JSON facultatif avec {{param}}. Sans lui, POST/PUT envoient les paramètres comme objet JSON.
`response_path`	Chemin à points facultatif (data.results) vers la partie de la réponse que l'IA doit lire.

Comment se fait l'appel

GET et DELETE ajoutent les paramètres à l'URL en query string. POST et PUT les envoient en body JSON, ou le body_template une fois rempli. Les en-têtes d'auth et les supplémentaires partent à chaque appel. Répondez 2xx avec du JSON : l'IA reçoit le body (ou la partie de response_path) en texte et s'en sert pour répondre. Un code autre que 2xx arrive à l'IA comme « API returned <status> » et elle dit au client qu'elle n'a pas pu consulter ; il n'y a pas de nouvelle tentative.

Comment en créer un

Canvas (newui.tbit.app) : demandez « quels outils personnalisés ai-je ? » → la liste propose « Nouvel outil… » ; chaque ligne ouvre l'outil avec Modifier. Un formulaire demande tout ce qui précède ; les secrets laissés vides lors d'une modification sont conservés.
MCP (Claude, ChatGPT…) : list_custom_tools pour les lire, manage_custom_tool avec action=create | update | delete. Le changement est proposé et vous le confirmez.
App de la plateforme : Intégrations → API personnalisée.

Exemple : créer depuis le MCP

json

manage_custom_tool
{
  "action": "create",
  "name": "consultar_credito",
  "description": "Consulta el estado de un crédito por número de cédula; devuelve saldo, cuotas pendientes y próxima fecha de pago.",
  "method": "GET",
  "endpoint": "https://api.tunegocio.com/v1/creditos",
  "parameters": [
    { "name": "cedula", "type": "string", "description": "Cédula del cliente, solo dígitos", "required": true }
  ],
  "auth_type": "BEARER",
  "auth_token": "<tu token>",
  "response_path": "data"
}

Ce que reçoit votre endpoint

Avec l'exemple ci-dessus, quand un client demande où en est son crédit, l'IA appelle :

http

GET https://api.tunegocio.com/v1/creditos?cedula=1032456789
Authorization: Bearer <tu token>
Accept: application/json

→ 200 { "data": { "saldo": 1250000, "cuotas_pendientes": 3, "proximo_pago": "2026-10-05" } }

Bonnes pratiques

Rédigez la description pour l'IA, pas pour un développeur : quand l'utiliser et ce qu'il renvoie.
Ne marquez comme obligatoire que ce que l'IA doit demander au client ; pour le reste, prévoyez une valeur par défaut de votre côté.
Gardez les GET idempotents : l'IA peut appeler le même outil deux fois dans une conversation si la première tentative a échoué.
Renvoyez un JSON petit et plat. Utilisez response_path si votre API enveloppe les résultats.