10 · apis

Functions: prepare your business APIs

A function turns an HTTPS URL of your system into a tool: the agent sends arguments as JSON, your API answers with JSON. Prepare one API per business action rather than one catch-all API.

Declare: a name (verb_object), a description (when to call it, when not to), the JSON schema of the arguments and the URL.
The agent sends a JSON body { function, arguments } to your URL. Method, headers (for example Authorization) and timeout are configurable.
Dry run: the test button runs the call with sample arguments, before anything is attached to a bot.
On your side: answer with 2xx and short, readable JSON (the model reads the response, truncated beyond a few thousand characters). A non-2xx status is passed to the agent as "Error: …": write a clear message.
An action that writes (cancellation, refund) must tolerate a replay: plan for an idempotency key.
Enterprise gateway: if your systems sit behind a gateway, connect it once in Integrations (URL, key never returned by the API, timeout from 5 to 60 s).
Private addresses are blocked by default; use a public HTTPS URL.

Function — schema and your API's response

// Schéma des arguments déclaré dans la fonction
{
  "type": "object",
  "properties": {
    "numero_commande": { "type": "string", "description": "Ex. CMD-2291" }
  },
  "required": ["numero_commande"]
}

// Appel envoyé par l'agent à votre URL HTTPS
POST https://api.votredomaine.com/suivi_commande
{ "function": "suivi_commande", "arguments": { "numero_commande": "CMD-2291" } }

// Réponse attendue : 2xx + JSON court
{ "statut": "en livraison", "livraison_prevue": "demain avant 18 h" }