Documentation · Le standard

Brancher un outil de réservation à l'Agent IA (API)

L'Agent IA du parcours d'appel prend des rendez-vous au téléphone : une coupe chez le coiffeur, une table au restaurant. Il peut lire les créneaux libres dans l'outil du lieu et lui envoyer les réservations. Cette page décrit ce que LeBigo envoie et ce qu'il attend en retour, pour un logiciel de réservation ou un scénario Make, Zapier ou n8n.

Les trois appels

Chacun est facultatif et se règle à part : méthode (GET, POST, PUT ou PATCH), adresse, en-têtes, corps modèle et délai. Sans méthode choisie : GET pour les disponibilités (POST si vous écrivez un corps modèle), POST pour la réservation et la confirmation. Les créneaux peuvent aussi venir des agendas LeBigo ou de son propre registre de places, et la réservation partir par e-mail ou dans le chat : ces cas-là n'appellent pas votre outil.

Les paramètres nommés

Écrits dans l'adresse, les en-têtes ou le corps modèle, ils sont remplacés au moment de l'appel :

• Disponibilités : {date}, {prestation}, {personne}, {personnes}, {duree}, {du} et {au}.
• Réservation et confirmation : tous, sauf {du} et {au}.
• Échappement : dans l'adresse, chaque valeur est échappée selon sa place (chemin ou paramètre de requête) ; dans le corps, en chaîne JSON, à mettre entre guillemets ({reponses} arrive donc en texte) ; dans un en-tête, telle quelle. Les nombres ({personnes}, {duree}) peuvent s'écrire sans guillemets.
• Un nom inconnu reste tel quel. Les variables du parcours ({caller.number}…) restent disponibles.

GET https://resa.exemple.fr/api/creneaux?date={date}&service={prestation}&couverts={personnes}

Disponibilités : la réponse attendue

Une réponse 2xx en JSON : une liste, ou un objet {"slots": [...]}. Chaque créneau est une heure, ou un objet :

["2026-10-18T14:00", "2026-10-18T14:30", "2026-10-18T16:00"]

{"slots": [
  {"start": "2026-10-18T14:00", "person": "Léa", "duration_min": 45},
  {"start": "2026-10-18T15:00:00+02:00", "person": "Marc"}
]}

• start : une heure sans fuseau est l'heure locale du lieu ; le RFC 3339 est aussi accepté.
• person et duration_min sont facultatifs. Sans durée, c'est celle de la prestation.
• Un créneau hors de la période {du} à {au} est ignoré ; l'ordre n'a pas d'importance.
• Une réponse 2xx illisible vaut une liste vide : aucun créneau.
• Un code 4xx ou 5xx, une redirection ou un délai dépassé : l'agent dit que le système de réservation ne répond pas et propose de prendre une demande ou un message.

Réservation : le JSON envoyé

Sans corps modèle, LeBigo envoie ce JSON (Content-Type: application/json, sauf si vous avez réglé un autre Content-Type) :

{
  "event": "booking.created",
  "reference": "bk_1a2b3c4d",
  "status": "requested",
  "service": "Table",
  "start": "2026-10-18T19:00:00+02:00",
  "end": "2026-10-18T20:30:00+02:00",
  "duration_min": 90,
  "party": 2,
  "caller": {"name": "M. Petit", "number": "+33612345678"},
  "answers": {"Allergies": "aucune"},
  "call_id": "…"
}

Dans booking.created, status vaut requested : c'est votre réponse qui décide. Il vaut confirmed seulement quand LeBigo a déjà pris la place lui-même (créneaux lus dans ses agendas ou son registre) : votre outil est alors prévenu, pas consulté.

Réservation : votre réponse

HTTP/1.1 409 Conflict
Content-Type: application/json

{"status": "refused", "reason": "complet",
 "alternatives": ["2026-10-18T21:00", {"start": "2026-10-19T19:00"}]}

Les alternatives se lisent comme les créneaux : des heures, ou des objets avec start. Quand LeBigo a déjà pris la place lui-même, un refus ne défait pas la réservation : il est seulement noté côté LeBigo.

Annulation et confirmation

• Annulation : l'appelant peut annuler par téléphone une réservation faite depuis son numéro. L'adresse de réservation reçoit le même JSON, avec "event": "booking.cancelled" et "status": "cancelled".
• Confirmation : l'adresse de confirmation reçoit booking.confirmation après chaque réservation (status confirmed ou requested), et booking.cancelled après chaque annulation. C'est le bon endroit pour envoyer un SMS à l'appelant : LeBigo n'en envoie pas.

La réponse à ces deux envois n'est pas lue. Il n'y a pas de nouvel essai : en cas d'échec, l'envoi est perdu pour votre outil, la réservation reste dans LeBigo.

Authentification

Ces appels ne portent pas de signature : c'est l'en-tête d'authentification réglé dans le bloc qui prouve qu'ils viennent de LeBigo. Votre outil doit refuser tout appel qui ne l'a pas.

La valeur secrète est scellée chez LeBigo : donnée une fois à votre partenaire, elle n'est plus jamais affichée, ni dans le parcours ni dans les journaux, et seul le serveur d'appel l'ouvre, au moment de l'appel. Pour la changer, on en scelle une nouvelle. Évitez de mettre un jeton dans l'adresse : elle, n'est pas secrète.

Limites

• https seulement : une adresse en http est refusée.
• Pas d'adresse privée : réseau local, 10.x, 172.16.x à 172.31.x, 192.168.x, localhost sont refusés. Pour tester depuis votre réseau, exposez une adresse publique.
• Pas de redirection : une réponse 3xx n'est pas suivie et compte comme un échec.
• 10 secondes au plus (5 par défaut) : l'appelant attend au bout du fil.
• 64 Kio de réponse au plus : au-delà, la réponse est coupée et ne se lit plus. Ne renvoyez que la période demandée.
• 10 en-têtes et 4 000 caractères de corps modèle au plus par appel.

Avec Make, Zapier ou n8n

• Prenez l'adresse d'un webhook entrant du scénario comme adresse de réservation, en POST, sans corps modèle : le scénario reçoit le JSON ci-dessus.
• Un webhook qui répond 200 tout de suite vaut acceptation : chaque réservation est annoncée comme faite. Pour pouvoir refuser, répondez depuis le scénario (réponse de webhook dans Make, nœud de réponse dans n8n) avec 409 ou {"status": "refused"}, en moins de 10 secondes.
• Pour seulement être prévenu (une ligne dans un tableur, un SMS), utilisez plutôt l'adresse de confirmation : sa réponse n'est pas lue.
• Vérifiez l'en-tête d'authentification dans le scénario, par un filtre ou la protection du webhook.