> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ouraicalling.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Calendrier & réservation

> Laissez les assistants vérifier la disponibilité et prendre rendez-vous en cours d'appel — via Cal.com, Calendly, Google Calendar, Outlook ou le moteur de réservation intégré avec des pages de réservation publiques

La prise de rendez-vous est le cas d'usage classique des agents vocaux : l'assistant vérifie les créneaux disponibles pendant l'appel, propose quelques options, puis réserve celui que l'appelant choisit. La plateforme prend en charge cela de deux manières, combinables librement :

1. **Intégrations de calendrier** — connectez une fois un fournisseur de planification externe (Cal.com, Calendly, Google Calendar, Outlook), attribuez-le à un assistant, et celui-ci obtient automatiquement des outils de réservation pour chaque appel.
2. **Le moteur de réservation intégré** — définissez vos propres types d'événements avec une disponibilité hebdomadaire, et obtenez une page de réservation publique et intégrable sur `/book/{workspace}/{slug}`, des e-mails d'invitation ICS, ainsi qu'une intégration `native` sur laquelle vos assistants peuvent réserver. Aucun compte externe requis.

## Aperçu des fournisseurs

| Fournisseur                 | Disponibilité                                                                 | Réservation                                                                               | Identifiants                                         |
| --------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| **Cal.com**                 | ✓ créneaux ouverts d'un type d'événement                                      | ✓ réservation directe                                                                     | Clé API (`cal_…`) + ID numérique du type d'événement |
| **Calendly**                | ✓ horaires disponibles d'un type d'événement                                  | ✓ réservation directe (forfaits Calendly payants) ou lien de planification à usage unique | Jeton d'accès personnel + URI du type d'événement    |
| **Google Calendar**         | ✓ libre/occupé d'un calendrier connecté                                       | ✓ création d'événement avec invitation des participants                                   | Connexion OAuth (une seule fois)                     |
| **Outlook / Microsoft 365** | ✓ libre/occupé via Microsoft Graph                                            | ✓ création d'événement avec invitation des participants                                   | Connexion OAuth (une seule fois)                     |
| **Natif (moteur intégré)**  | ✓ calculé à partir de la disponibilité hebdomadaire de votre type d'événement | ✓ réservation directe + e-mail ICS                                                        | aucun                                                |

<Note>
  **Mode lien Calendly** : l'API de planification de Calendly nécessite un forfait Calendly payant. Si votre forfait ne permet pas la réservation directe, réglez le `booking_mode` de l'intégration sur `link` — l'assistant convient alors d'un horaire approximatif avec l'appelant et envoie un **lien de planification à usage unique** par SMS ou e-mail (`link_channel`) plutôt que de réserver directement. Les intégrations qui rencontrent cette restriction du forfait payant au moment de l'appel sont signalées avec le statut `link_mode`.
</Note>

## Connecter une intégration

Allez dans **Outils → Intégrations** et choisissez une carte de fournisseur :

* **Cal.com** — collez votre clé API (Cal.com → Settings → Developer → API Keys) et l'ID numérique du type d'événement (visible dans l'URL du type d'événement). Le fuseau horaire peut être personnalisé — veillez à ce qu'il corresponde à celui du type d'événement Cal.com.
* **Calendly** — collez un jeton d'accès personnel (Calendly → Integrations & apps → API & webhooks), puis choisissez le type d'événement. Sélectionnez le mode de réservation (`api` ou `link`) ainsi que le canal d'envoi du lien.
* **Google / Outlook** — cliquez sur **Connecter** et validez le consentement OAuth. La connexion est stockée au niveau de l'espace de travail et réutilisée par toutes les intégrations et tous les types d'événements qui y font référence.
* **Natif** — choisissez l'un de vos types d'événements de réservation (voir ci-dessous).

Chaque intégration est **vérifiée avant d'être enregistrée** : une clé API, un jeton ou un ID de type d'événement invalide est rejeté avec un message d'erreur clair et n'est jamais stocké. Les valeurs secrètes ne quittent jamais le serveur — les réponses les masquent sous la forme `•••` (envoyez `•••` lors d'une mise à jour pour conserver la valeur déjà stockée).

## Attribution à un assistant

Ouvrez les paramètres de l'assistant et cochez les intégrations qu'il doit utiliser (ou passez par `PUT /api/v1/assistants/{id}/integrations`). Pour **chaque intégration attribuée**, l'assistant reçoit ces outils à chaque appel :

| Outil                                          | Type                                                                   | Ce qu'il fait                                                                                                                                                                                                                                       |
| ---------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `check_availability(start_date, end_date?)`    | lecture seule, interruptible                                           | Récupère les créneaux disponibles pour la plage de dates et les énonce dans le fuseau horaire de l'assistant (avec un plafond, pour que l'agent ne récite jamais 200 créneaux).                                                                     |
| `book_appointment(name, email, start, notes?)` | écriture — s'exécute avec une phrase de remplissage, non interruptible | Réserve le créneau choisi. En cas de succès, l'heure de début et l'ID de la réservation sont stockés comme variables d'appel pour les flows, l'analyse et les webhooks. Si le créneau vient d'être pris, l'agent est invité à en proposer un autre. |
| `send_booking_link(email?, phone?)`            | Mode lien Calendly uniquement                                          | Crée un lien de planification à usage unique et l'envoie par SMS ou e-mail.                                                                                                                                                                         |

Si plusieurs intégrations sont attribuées, le nom de l'intégration est ajouté en suffixe au nom de l'outil (par exemple `check_availability_sales`). Les créneaux sont toujours annoncés dans le **fuseau horaire de l'assistant** — configurez-le dans ses paramètres.

<Tip>
  Indiquez à l'assistant **quand** réserver dans son prompt, par exemple : *« Avant de proposer un horaire, appelle check\_availability. Une fois que l'appelant confirme un créneau, appelle book\_appointment avec son nom et son e-mail. »*
</Tip>

## Le moteur de réservation intégré

Créez des types d'événements dans **Réservation**, depuis le tableau de bord (ou via l'API/MCP) :

* **Nom, slug, durée** — le slug est unique au sein de l'espace de travail et devient l'URL de la page publique `/book/{workspace}/{slug}` (`workspace` = `booking_handle` du tenant).
* **Disponibilité hebdomadaire** — plages horaires par jour de la semaine, dans le fuseau horaire du type d'événement, par exemple du lundi au vendredi de 9h à 17h.
* **Marges et règles** — marge avant/après chaque réservation, préavis minimum, horizon de réservation (`max_days_ahead`) et incrément des créneaux.
* **Synchronisation du calendrier** (facultatif) — associez un calendrier Google/Outlook connecté : ses plages occupées sont déduites des créneaux proposés, et les réservations confirmées sont poussées sous forme d'événements de calendrier (les participants reçoivent l'invitation du fournisseur).

### Page de réservation publique et intégration

Chaque type d'événement actif dispose d'une page publique aux couleurs du tenant, à l'adresse `https://<your-domain>/book/{workspace}/{slug}` — aucune connexion requise. Intégrez-la où vous voulez :

```html theme={null}
<iframe src="https://<your-domain>/book/acme/intro-call"
        style="width:100%;min-height:640px;border:0" loading="lazy"></iframe>
```

Les visiteurs choisissent un créneau (affiché dans leur propre fuseau horaire), saisissent leur nom et leur e-mail, et reçoivent un **e-mail de confirmation avec une invitation calendrier ICS**, ainsi qu'un lien d'annulation. Les doubles réservations sont impossibles — une contrainte d'exclusion au niveau de la base de données protège le créneau même lorsqu'un visiteur web et un assistant réservent au même moment ; le perdant reçoit un message convivial indiquant que le créneau vient d'être pris.

### Réservation depuis un appel

Créez une intégration avec le fournisseur **`native`** pointant vers le type d'événement, puis attribuez-la à un assistant — les réservations effectuées en cours d'appel arrivent alors dans le même calendrier avec `source: "call"` et un lien vers l'enregistrement de l'appel.

## Limitation par le plan

L'ensemble de la fonctionnalité est conditionné par l'indicateur de plan **`calendar_integrations`** (administration de la plateforme → Plans). Sans lui, la création d'intégrations ou de types d'événements renvoie `403` ; les pages de réservation publiques existantes cessent d'accepter de nouvelles réservations.

## API et MCP

Tout ce qui précède est disponible via l'[API REST publique](/api-reference/introduction) ainsi que sous forme d'outils MCP à l'adresse `https://<your-domain>/mcp` :

`GET /api/v1/bookings` et `list_bookings` prennent en charge les filtres par type d'événement, source et date. Utilisez `view=upcoming|unconfirmed|recurring|past|cancelled` pour retrouver les mêmes vues de réservation que dans le tableau de bord, ou appliquez un filtre `status` exact ; `view` et `status` s'excluent mutuellement.

| REST                                                                                        | Outil MCP                                                                                                        | Portée                             |
| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `GET/POST /api/v1/integrations`, `GET/PATCH/DELETE /api/v1/integrations/{id}`               | `list_integrations`, `get_integration`, `create_integration`, `update_integration`, `delete_integration`         | `integrations:read/write`          |
| `GET/PUT /api/v1/assistants/{id}/integrations`                                              | `get_assistant_integrations`, `set_assistant_integrations`                                                       | `integrations:*` ou `assistants:*` |
| `GET/POST /api/v1/booking-event-types`, `GET/PATCH/DELETE /api/v1/booking-event-types/{id}` | `get_booking_event_types`, `create_booking_event_type`, `update_booking_event_type`, `delete_booking_event_type` | `bookings:read/write`              |
| `GET /api/v1/bookings`, `GET /api/v1/bookings/{id}`, `POST /api/v1/bookings/{id}/cancel`    | `list_bookings`, `get_booking`, `cancel_booking`                                                                 | `bookings:read/write`              |

L'annulation d'une réservation envoie une mise à jour ICS `METHOD:CANCEL`, ce qui fait disparaître automatiquement le rendez-vous du calendrier de l'invité.