Bookivox Documentation

À quoi ça sert

L’intégration Cal.com permet à votre agent de gérer des rendez-vous pendant l’appel : trouver un créneau libre, réserver un rendez-vous et consulter les réservations existantes. Comme pour les autres intégrations, vous branchez votre propre compte : Bookivox ne fournit aucun identifiant. Vous créez une clé API dans Cal.com, la collez dans Bookivox, puis cochez les actions à exposer.

Cette intégration écrit réellement dans Cal.com : une réservation créée apparaît dans votre agenda. Le client fournit sa propre clé ; Bookivox ne fournit aucun identifiant.

Ce qu’il faut préparer

Élément	D’où il vient	Format attendu
Clé API	Cal.com : Paramètres → Développeur → Clés API	Chaîne commençant par `cal_live_` ou `cal_test_`, affichée une seule fois
Identifiant du type de rendez-vous	Cal.com, sur le type de rendez-vous concerné	Identifiant numérique (`eventTypeId`), ou slug (`eventTypeSlug`) accompagné du nom d’utilisateur de l’hôte

La clé donne les mêmes droits que votre session Cal.com. Préférez un compte dédié à l’IA si votre organisation le permet, et gardez la clé cal_test_ pour les essais.

Connecter Cal.com

Créer la clé API

Dans Cal.com, ouvrez Paramètres → Développeur → Clés API et créez une clé dédiée à Bookivox. Copiez-la : elle commence par cal_live_ ou cal_test_ et n’est affichée qu’une fois.

Relever le type de rendez-vous

Notez l’identifiant du type de rendez-vous à utiliser (eventTypeId), ou son slug (eventTypeSlug) et le nom d’utilisateur de l’hôte.

Saisir la clé

Dans Intégrations → Cal.com, collez la clé. Le formulaire vérifie le préfixe avant l’enregistrement.

Cocher les actions

Sélectionnez les actions à exposer. Chacune devient un outil indépendant.

Vérifier la connexion

Cliquez sur Créer les outils. Un bandeau vert confirme la création et indique le nombre d’outils créés. La clé disparaît du formulaire : elle reste chiffrée et n’est plus jamais réaffichée.

Compléter la connexion

La carte Connexions Cal.com liste les comptes reliés à l’organisation avec leur état (Complète ou Partielle). Le bouton Créer ajoute une action manquante sans ressaisir la clé.

Ce que l’agent peut faire

Action	Usage	Exemple de demande
Créer une réservation (`create_booking`)	Réserve un créneau Cal.com pendant l’appel	« Réservez-moi mardi à 10 h. »
Consulter les réservations (`list_bookings`)	Liste les rendez-vous, filtrables par statut ou participant	« J’ai bien un rendez-vous jeudi ? »
Trouver un créneau (`get_available_slots`)	Liste les créneaux libres d’un type de rendez-vous sur une période	« Qu’est-ce que vous avez en fin de semaine ? »

Chaque action crée un outil distinct : vous pouvez n’en activer qu’une partie, et n’attacher à un agent que celles dont il a besoin.

Toutes les dates (start, startTime, endTime, afterStart, beforeEnd) doivent être en ISO 8601 UTC, par exemple 2026-05-04T09:00:00Z. Annoncez ensuite l’heure au client dans son fuseau.

Cas d’usage

Cas d’usage	Ce que fait l’agent	Résultat pour le client
Proposer puis réserver	L’agent appelle `get_available_slots` sur la période demandée, annonce deux ou trois créneaux, puis `create_booking` sur celui choisi.	Le rendez-vous est pris pendant l’appel, avec des dates en ISO 8601 UTC.
Confirmer un rendez-vous existant	L’agent appelle `list_bookings` filtré par participant ou par statut.	Le client sait si son rendez-vous est bien enregistré.
Éviter le doublon	Avant de réserver, l’agent appelle `list_bookings` pour vérifier qu’aucun rendez-vous identique n’existe.	Aucun second rendez-vous n’est créé pour la même demande.
Mesurer la charge d’une journée	L’agent appelle `list_bookings` avec `afterStart` et `beforeEnd` sur la journée.	L’agent propose des créneaux réellement tenables.

Comment ça marche

Bookivox crée une credential bearer_token contenant la clé cal_live_… ou cal_test_…. Le backend l’envoie en en-tête Authorization: Bearer.
Toutes les requêtes partent vers l’URL de base https://api.cal.com/v2.
La version d’API n’est pas globale : elle voyage dans l’en-tête cal-api-version et diffère par endpoint. Le preset la fixe par action : 2026-02-25 pour la création de réservation, 2026-05-01 pour la liste des réservations, 2024-09-04 pour les créneaux disponibles.
Un outil http_api par action est créé, avec config.provider = "cal-com", config.operation et un timeout de 10 000 ms.
create_booking est un POST sur /bookings ; list_bookings un GET sur /bookings ; get_available_slots un GET sur /slots/available.
Cal.com limite le débit à 120 requêtes par minute par clé.
Seuls les endpoints de collection sont exposés : l’URL de l’outil est envoyée telle quelle, donc les chemins avec identifiant (/v2/bookings/{uid}) ne sont pas accessibles.

Rédiger la description de l’outil

La description de l’outil est ce qui décide quand l’agent appelle Cal.com. Rédigez-la comme une consigne :

Utiliser cet outil quand le client veut un rendez-vous : proposer d'abord
les créneaux libres, puis réserver celui qu'il choisit.

Avec Trouver un créneau et Créer une réservation tous les deux actifs, précisez dans le prompt l’ordre : proposer, faire choisir, puis réserver. Sans cela, l’agent peut réserver une heure qui n’a jamais été confirmée par le client.

Sécurité

Risque	Ce que fait le preset
Clé exposée	Elle vit dans une credential chiffrée, jamais dans la définition de l’outil ni dans un prompt. Elle n’est jamais réaffichée après l’enregistrement.
Écritures non voulues	Une seule action écrit : `create_booking`. Aucune annulation ni déplacement de réservation n’est exposé.
Portée excessive	La clé donne les droits de votre session Cal.com : utilisez un compte dédié à l’IA si possible.
Mauvais compte	L’URL est figée sur `https://api.cal.com/v2` : l’outil ne peut pas viser un autre serveur.
Version d’API	`cal-api-version` est fixée par le preset, endpoint par endpoint : l’agent ne peut pas la changer.
Volume d’appels	Le preset reste sur des actions ciblées ; au-delà de 120 requêtes par minute, Cal.com renvoie `429`.

Utilisez une clé cal_test_ pour les essais et une clé cal_live_ seulement en production. En cas de doute, révoquez la clé dans Cal.com et recréez la connexion.

Ce qui est déconseillé

Usage	Pourquoi
Envoyer une heure locale non convertie	Les dates doivent être en ISO 8601 UTC : une heure locale décale le rendez-vous.
Réserver sans avoir proposé de créneau	Vous risquez de créer un rendez-vous à une heure non confirmée par le client.
Annuler ou déplacer un rendez-vous	Hors périmètre : aucune action de ce type n’est exposée.
Interroger un rendez-vous par identifiant	Le preset ne gère que les collections, pas les chemins avec identifiant.
Tâches planifiées	Un outil d’agent s’exécute pendant l’appel, pas en tâche de fond.

Limites et dépannage

Symptôme	Cause probable	Correction
Erreur `401`	Clé erronée, révoquée ou recopiée avec un espace.	Recopier la clé brute et recréer la connexion.
Erreur `403`	La clé n’a pas accès au type de rendez-vous visé.	Vérifier l’hôte et le type de rendez-vous dans Cal.com.
Erreur `404`	Type de rendez-vous inconnu, ou endpoint indisponible pour cette version.	Vérifier `eventTypeId` ou le couple `eventTypeSlug` + `username`.
Erreur `400` / `422`	Charge utile invalide : date non UTC, participant incomplet, `eventTypeId` absent.	Envoyer une date ISO 8601 UTC, un objet `attendee` avec nom et e-mail, et un type de rendez-vous.
Erreur `429`	Plus de 120 requêtes par minute pour cette clé.	Espacer les appels ; ne pas attacher plusieurs agents très actifs à la même clé.
Erreur `5xx`	Incident côté Cal.com.	Réessayer plus tard ; contacter Cal.com si cela dure.
« Clé invalide »	La clé ne commence pas par `cal_live_` ou `cal_test_`.	Recopier la valeur exacte fournie par Cal.com.
Le rendez-vous tombe à la mauvaise heure	Date envoyée en heure locale au lieu d’UTC.	Convertir l’heure en UTC avant l’appel, et annoncer l’heure locale au client.
L’agent répond « de tête »	L’outil n’est pas attaché à l’agent, ou il est inactif.	L’activer et l’attacher au nœud agent.
« Créer » ne fait rien	L’action est déjà créée pour cette connexion.	Elle porte la mention Déjà créé ; rien à faire.

Cal.com n’est pas relié ici par un serveur MCP : chaque action est un outil HTTP distinct, ce qui permet à l’agent de choisir précisément une action plutôt que d’appeler un serveur générique.

Intégrations

Toutes les intégrations et les catégories d’outils.

API HTTP

Comprendre les outils HTTP : paramètres, presets, credentials.

Prise en main

LABS

Construire

Préparer

Piloter

Revendeur (White-label)

Intégration : Cal.com

À quoi ça sert

Ce qu’il faut préparer

Connecter Cal.com

Ce que l’agent peut faire

Cas d’usage

Comment ça marche

Rédiger la description de l’outil

Sécurité

Ce qui est déconseillé

Limites et dépannage

Intégrations

API HTTP

​À quoi ça sert

​Ce qu’il faut préparer

​Connecter Cal.com

​Ce que l’agent peut faire

​Cas d’usage

​Comment ça marche

​Rédiger la description de l’outil

​Sécurité

​Ce qui est déconseillé

​Limites et dépannage

Intégrations

API HTTP

À quoi ça sert

Ce qu’il faut préparer

Connecter Cal.com

Ce que l’agent peut faire

Cas d’usage

Comment ça marche

Rédiger la description de l’outil

Sécurité

Ce qui est déconseillé

Limites et dépannage