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

# Calendly

> Calendly verbinden - freie Termine prüfen und Termine direkt buchen.

## Überblick

Mit der **Calendly-Integration** kann Ihr Voice Agent freie Termine für Ihre Calendly-Termintypen (event types) prüfen und Termine direkt buchen. Calendly ist ein reines **Buchungs-Tool**: Der Agent fragt verfügbare Slots ab und bucht den vom Anrufer gewählten Termin für den konfigurierten Termintyp.

Anders als bei der Outlook-Integration (nur OAuth) gibt es bei Calendly **zwei Verbindungsarten**: den empfohlenen **OAuth-Flow** und ein **persönliches Zugriffstoken (PAT)**. Sie verbinden Calendly **einmal** und erstellen daraus anschließend die gewünschten Termin-Tools.

<Info>
  **Sicherheit:** Beim OAuth-Flow werden Sie zu Calendly weitergeleitet, um den Zugriff zu bestätigen. Die Zugangsdaten werden verschlüsselt auf dem Server gespeichert und sind nur für Ihren Account zugänglich.
</Info>

## Integration einrichten

1. Öffnen Sie die **Tools**-Seite in der Sidebar
2. Klicken Sie auf **Create tool** (Tool erstellen) und wählen Sie **Calendly**
3. Wählen Sie im Dialog die **Verbindungsart** - **Mit Calendly verbinden** (OAuth, empfohlen) oder **Persönliches Zugriffstoken**

### Mit Calendly verbinden (OAuth)

**Empfohlen.** OAuth gewährt einen eingeschränkten, jederzeit widerrufbaren Zugriff mit rotierenden Token.

1. Wählen Sie **Mit Calendly verbinden** und klicken Sie auf **Connect Calendly** - es öffnet sich ein neues Tab mit dem Calendly-Zustimmungsbildschirm
2. Folgen Sie dem OAuth-Flow von Calendly und bestätigen Sie den angeforderten Zugriff
3. Nach der Zustimmung kehren Sie automatisch zur **Tools**-Seite zurück und können die Termintypen auswählen

### Persönliches Zugriffstoken (PAT)

Für Fälle, in denen OAuth nicht in Frage kommt (z. B. interne Richtlinien). Wählen Sie im Dialog **Persönliches Zugriffstoken** und folgen Sie diesen Schritten:

1. Melde dich bei Calendly an und öffne Integrationen & Apps > API und Webhooks (calendly.com/integrations/api\_webhooks).
2. Klick unter Persönliche Zugriffstoken auf Neues Token generieren.
3. Gib dem Token einen Namen, zum Beispiel "AI Pro Sprachassistent", und klick auf Token erstellen.
4. Kopier das Token sofort - Calendly zeigt es dir nur ein einziges Mal an.
5. Füg es unten im Feld Zugriffstoken ein und klick auf Verbinden.

<Info>
  Dieses Token gibt vollen Zugriff auf dein Calendly-Konto und läuft nicht ab. Du kannst es aber jederzeit auf derselben Calendly-Seite wieder widerrufen. Wenn du lieber einen eingeschränkten und leicht widerrufbaren Zugang möchtest, nimm "Mit Calendly verbinden" (OAuth).
</Info>

### Nach dem Verbinden

Unabhängig von der Verbindungsart geht es danach gleich weiter:

1. Wählen Sie einen oder mehrere **Termintypen** (event types) aus, die für den verbundenen Account erstellt werden sollen
2. Hinterlegen Sie eine **Standard-Buchungs-E-Mail** - diese ist für Buchungen erforderlich, da die E-Mail nicht zuverlässig per Sprache erfasst werden kann. Calendly versendet seine Bestätigung an diese Adresse
3. Klicken Sie auf **Create**
4. Öffnen Sie den gewünschten Voice Agent und wechseln Sie in den **Tools**-Tab. Aktivieren Sie dort die Calendly-Tools für diesen Agent

<Info>
  **Gemeinsame Tools:** Wie alle Tools stehen auch die Calendly-Tools nach dem Erstellen global zur Verfügung. Sie müssen sie pro Voice Agent nur noch im **Tools**-Tab aktivieren. Mehr dazu unter [Tools](/docs/de/tools).
</Info>

## Verfügbare Tools

Beim Verbinden werden bis zu zwei Tools angelegt:

### `calendly_get_availability`

Prüft freie Termine für den konfigurierten Calendly-Termintyp. Typischer Einsatz: Der Anrufer fragt nach freien Terminen, bevor er bucht.

| Parameter | Typ    | Pflicht | Beschreibung                                                                                                                                                                      |
| --------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `start`   | string | Ja      | Startdatum/-zeit in der lokalen Zeit des Anrufers, ISO-Format ohne Zeitzonen-Angabe (z. B. `2026-06-10T13:00:00`). Wird serverseitig in die vorkonfigurierte Zeitzone umgerechnet |
| `end`     | string | Ja      | Ende des Suchfensters, gleiches Format. Muss strikt nach `start` liegen (nicht gleich). Fenster max. 7 Tage                                                                       |

### `calendly_book_appointment`

Bucht einen Termin für den konfigurierten Calendly-Termintyp. Typischer Einsatz: Der Anrufer hat einen freien Slot gewählt und der Termin wird gebucht.

| Parameter  | Typ    | Pflicht | Beschreibung                                                                                 |
| ---------- | ------ | ------- | -------------------------------------------------------------------------------------------- |
| `fullname` | string | Ja      | Vollständiger Name des Anrufers                                                              |
| `start`    | string | Ja      | Exakte Startzeit des gewählten Slots, unverändert aus `calendly_get_availability` übernommen |

<Info>
  **Keine Tool-Parameter:** Telefonnummer und E-Mail sind **keine** Tool-Parameter - die Nummer kommt aus dem Anruf, die E-Mail aus der hinterlegten **Standard-Buchungs-E-Mail**.
</Info>

<Tip>
  **Typischer Ablauf:** Kombinieren Sie beide Tools - der Voice Agent ruft zuerst `calendly_get_availability` auf, um freie Slots zu nennen, und bucht den vom Anrufer gewählten Termin anschließend mit `calendly_book_appointment` (die `start`-Zeit unverändert übernommen).
</Tip>

### Mehrere Termintypen

Ist das Tool mit **mehr als einem** Calendly-Termintyp konfiguriert, wird in **beide** Schemata ein zusätzlicher Pflicht-Parameter `event_type` injiziert. Bei einem einzigen Termintyp entfällt er - der Termintyp wird dann serverseitig gebunden.

```json theme={null}
"event_type": {
  "type": "string",
  "enum": ["<Name Termintyp 1>", "<Name Termintyp 2>"],
  "description": "Welcher Termintyp gebucht/geprüft werden soll. Gleicher Wert für Verfügbarkeit und Buchung."
}
```

<Warning>
  **Buchung nicht möglich:** Bei Termintypen mit erforderlichen benutzerdefinierten Fragen müssen Anrufer Pflichtfragen beantworten, die der Assistent noch nicht erfassen kann - Buchungen schlagen daher fehl. Für Buchungen eignet sich eine Terminart ohne Pflichtfragen; für Verfügbarkeitsabfragen funktioniert sie weiterhin. Solche Termintypen werden auf der Einrichtungsseite gekennzeichnet.
</Warning>