Bookivox Documentation

Vue d’ensemble

Une intégration http_api permet à un agent d’appeler vos propres API pendant l’appel. Elle est réutilisable sur plusieurs agents.

Version produit pas-à-pas : Intégration : Appel HTTP. Cette page détaille le pilotage par API.

Anatomie d’une intégration

Champ	Rôle
`name`	Nom parlant (« Vérifier le stock »)
`description`	Quand l’agent doit appeler l’outil
`category`	`http_api` (déduite de `definition.type`)
`icon` / `icon_color`	Identification visuelle
`definition`	Configuration de l’appel (voir ci-dessous)

Définition `http_api`

Le champ definition porte un objet dont type vaut "http_api".

Champ	Type	Requis	Défaut	Description
`type`	string	oui	—	`"http_api"`. Détermine la catégorie de l’outil.
`method`	string	oui	—	`GET`, `POST`, `PUT`, `PATCH` ou `DELETE`.
`url`	string	oui	—	URL cible (http/https). L’authentification ne va pas dans l’URL.
`headers`	object	non	`null`	En-têtes statiques envoyés à chaque requête. Pas de secret ici.
`credential_uuid`	string	non	`null`	Référence à un identifiant géré côté Bookivox, pour l’authentification.
`parameters`	array	non	`null`	Paramètres que le modèle doit fournir à l’appel.
`preset_parameters`	array	non	`null`	Paramètres injectés par Bookivox (valeur fixe ou contexte du workflow).
`timeout_ms`	int	non	`5000`	Délai d’expiration de la requête (ms). Minimum 1.
`customMessage`	string	non	`null`	Message joué après exécution de l’outil.
`customMessageType`	string	non	`null`	`text` ou `audio`.
`customMessageRecordingId`	string	non	`null`	ID d’enregistrement si `customMessageType = audio`.

`parameters` (fournis par le modèle)

Utilisez-les pour les valeurs que l’agent doit extraire de la conversation.

Champ	Description
`name`	Nom du paramètre, utilisé comme clé dans la requête.
`type` / `description`	Type attendu et explication pour le modèle.
`required`	Si `true`, le modèle doit le fournir.

`preset_parameters` (injectés)

Pour les valeurs que Bookivox injecte automatiquement : valeur fixe, ou variable de contexte ({{produit_ref}}, identifiant d’appel…).

Exemple de définition

{
  "name": "Vérifier le stock",
  "description": "Appeler quand le client demande la disponibilité d'un produit.",
  "category": "http_api",
  "definition": {
    "type": "http_api",
    "method": "GET",
    "url": "https://api.mon-shop.com/disponibilite",
    "credential_uuid": "<credential_uuid>",
    "preset_parameters": [
      { "name": "ref", "value": "{{produit_ref}}" }
    ],
    "timeout_ms": 5000,
    "customMessage": "Je vérifie la disponibilité, un instant.",
    "customMessageType": "text"
  }
}

L’authentification ne se met pas dans url ni dans headers. Stockez le secret dans le gestionnaire d’identifiants et référencez-le via credential_uuid. Ne mettez jamais de secret dans description.

Attacher l’outil à un agent

Dans le graphe, l’outil est référencé sur le nœud agent (agentNode) via son tool_uuid. Récupérez-le ensuite par API :

GET /api/v1/api/tools/{tool_uuid}

Outil vs récupération pré-appel

	Outil `http_api`	Nœud Webhook
Moment	Pendant l’appel	Avant l’appel
Décidé par	Le modèle, selon la conversation	Le workflow, de façon déterministe

Sécurité

Utilisez HTTPS uniquement.
Appliquez le moindre privilège au jeton d’API utilisé.
Validez côté serveur tous les paramètres reçus : l’agent peut être manipulé par un appelant malveillant.
N’inscrivez jamais de secret dans la description.
Si vos API sont publiques, protégez-les contre l’usage abusif (quotas, rate-limiting) : un agent peut générer un volume d’appels imprévu.

Guide produit

Créer l’intégration pas à pas.

Outils (API)

Schéma complet de création d’outil.

Nœud Webhook

Envoyer et recevoir des données autour de l’appel.

Endpoints

Cheatsheet complet.

Last modified on October 28, 2026

Agents

Base de connaissance

Campagnes

Chat texte

Clés API

Crédits et usage

Node-types

Outils

Téléphonie

Templates

Intégrations HTTP (API)

Vue d’ensemble

Anatomie d’une intégration

Définition `http_api`

`parameters` (fournis par le modèle)

`preset_parameters` (injectés)

Exemple de définition

Attacher l’outil à un agent

Outil vs récupération pré-appel

Sécurité

Guide produit

Outils (API)

Nœud Webhook

Endpoints

​Vue d’ensemble

​Anatomie d’une intégration

​Définition http_api

​parameters (fournis par le modèle)

​preset_parameters (injectés)

​Exemple de définition

​Attacher l’outil à un agent

​Outil vs récupération pré-appel

​Sécurité

Guide produit

Outils (API)

Nœud Webhook

Endpoints

Vue d’ensemble

Anatomie d’une intégration

Définition `http_api`

`parameters` (fournis par le modèle)

`preset_parameters` (injectés)

Exemple de définition

Attacher l’outil à un agent

Outil vs récupération pré-appel

Sécurité