Réservation avec Cal.com

Connecter votre calendrier#

Ouvrez Agent → Actions → Cal.com. Saisissez une clé API Cal.com commençant par cal_, l'identifiant numérique positif du type d'événement et un fuseau horaire IANA tel que Asia/Seoul. Choisissez Enregistrer la connexion. Chaque agent dispose de sa propre connexion. La clé est chiffrée côté serveur ; le tableau de bord n'en affiche que les quatre derniers caractères. Lorsque vous mettez à jour une connexion existante, laissez le champ de la clé vide pour la conserver.

Choisissez Tester la connexion pour lire jusqu'à trois prochains créneaux sur les sept jours à venir, à partir des paramètres saisis. Ce test n'enregistre pas la connexion et ne crée aucune réservation. L'absence de créneaux peut simplement signifier que le type d'événement n'a aucune disponibilité sur cette période. Si le test échoue, vérifiez la clé, le type d'événement et le planning dans Cal.com. La suppression de la connexion interrompt les nouvelles réservations Cal.com ; elle n'annule pas les réservations existantes.

Les paiements ne sont pas pris en charge. Google Calendar constitue une option distincte, qui n'est pas encore disponible pour tous.

Des créneaux à la réservation#

1. L'agent appelle find_slots pour obtenir les vraies disponibilités futures. Il présente jusqu'à huit horaires dans le fuseau horaire configuré. La plage par défaut va d'aujourd'hui jusqu'à sept jours plus tard ; l'intervalle maximal est de 14 jours. Lorsqu'un seul horaire est disponible, il est présenté seul.
2. Le client choisit un horaire et fournit son nom, son e-mail et, facultativement, une note. L'agent vérifie à nouveau que l'horaire est libre et qu'il a bien été proposé dans cette conversation. Les propositions de créneaux expirent au bout de 15 minutes.
3. Une carte de confirmation indique la date, l'heure, le fuseau horaire et les informations du participant. Le client doit appuyer sur Confirmer. Un message dans le chat ou la simple sélection d'un horaire ne réserve rien. La proposition expire au bout de 15 minutes et ne bloque pas le créneau.
4. Ce n'est qu'après la confirmation que l'adaptateur demande la réservation à Cal.com. Un résultat Cal.com accepted devient done, avec l'UID de la réservation comme référence. Les statuts pending ou awaiting_host restent en attente ; un refus ou une annulation devient un échec.

Sur les canaux de messagerie, les propositions de réservation ne sont disponibles que dans les conversations privées. La répétition ne appelle pas Cal.com et ne crée aucune réservation. Sans connexion Cal.com, le flux existant de demande de réservation reste disponible ; il ne prouve pas qu'un créneau a été réservé dans un calendrier. Modifier la clé, le type d'événement ou le fuseau horaire invalide la cible d'exécution d'une proposition : recommencez après toute modification de la connexion.

Si un créneau est pris ou si le résultat est incertain#

Un autre client peut prendre un créneau avant que la confirmation ne soit terminée. Si l'horaire n'est plus libre, l'agent indique qu'il n'est pas disponible ; si Cal.com refuse la réservation lors de sa création, le reçu indique un échec. Demandez de nouveaux horaires et confirmez une nouvelle proposition. Le reçu d'échec ne joint pas automatiquement de nouveaux choix.

Un délai d'attente réseau ne prouve ni l'échec ni la réussite. Le reçu affiche un résultat inconnu pendant que le service effectue une nouvelle vérification. Le point de terminaison de création de Cal.com n'a pas de contrat d'idempotency-key documenté ; l'adaptateur enregistre donc l'identifiant d'exécution dans metadata.maf_run et recherche cette réservation, tous statuts et toutes pages confondus, avant de retenter la création. Une recherche incomplète n'autorise jamais une nouvelle requête de création. Cela réduit le risque de doublon, mais ne constitue pas une garantie d'exécution unique (exactly-once) offerte par le fournisseur. Avant de faire une nouvelle réservation après l'épuisement des tentatives, vérifiez dans Cal.com.

L'approbation de l'hôte dans Cal.com est distincte de l'approbation du propriétaire pour les actions de modification personnalisées. Une réservation Cal.com en attente n'est pas actualisée automatiquement par cette intégration ; vérifiez son statut final dans Cal.com. Le widget web peut interroger régulièrement le reçu d'exécution enregistré, et les canaux privés pris en charge reçoivent des reçus différés, dans la limite de leurs fenêtres de service. Consultez la remise des reçus.

Versions de l'API et vérifications avant mise en production#

L'adaptateur envoie une authentification Bearer et les valeurs cal-api-version suivantes, propres à chaque point de terminaison, vérifiées dans la documentation officielle le 2026-10-13 :

Avant de l'utiliser avec des clients, testez une réservation contrôlée, vérifiez l'UID dans Cal.com, essayez un créneau déjà pris et contrôlez les reçus sur chaque canal prévu. Un test de connexion réussi prouve uniquement qu'une lecture de créneaux fonctionne, pas qu'une vraie réservation est possible ni que la configuration est prête pour la production.