Zum Hauptinhalt springen
telli + Custom calendar integration

​
Überblick

Mit der Option für einen eigenen Kalender kannst du dein bestehendes Kalender- oder Terminsystem mit telli-Agenten verbinden. Nutze diese Option, wenn telli mit deiner eigenen Buchungsinfrastruktur statt mit einem eingebauten Anbieter arbeiten soll.

​
Bevor du beginnst

  • Ein telli-Agent, der Termine buchen soll
  • Ein API-Endpoint, der verfügbare Terminslots zurückgibt
  • Ein API-Endpoint, der einen ausgewählten Terminslot bucht
  • Öffentlich erreichbare Endpunkte, die telli aufrufen kann

​
Eigenen Kalender in telli einrichten

1

Agent öffnen

Öffne den Agenten, den du in telli konfigurieren willst.
2

Generic Calendar auswählen

Wähle in Kalender-Integration die Option Generic Calendar.
3

Endpoints eintragen

Hinterlege die Available URL und, wenn telli Buchungen ausführen soll, die Book URL deiner Scheduling-API.
4

Agent speichern

Speichere den Agenten, damit telli Verfügbarkeiten abrufen und Termine über deine Endpunkte buchen kann.

​
Request-Ablauf

​
Endpunkte

Für eine vollständige Terminbuchung implementierst du beide Endpunkte unten. Wenn telli nur Verfügbarkeiten abrufen soll, kann der Buchungs-Endpoint leer bleiben.

​
Verfügbare Slots abrufen

Dieser Endpoint gibt eine Liste verfügbarer Terminslots zurück. 
POST /available

{
  "contact": {
    "id": "telli contact identifier",
    "type": "Contact",
    "externalId": "your contact identifier",
    "externalUrl": null,
    "salutation": null,
    "firstName": "Ada",
    "lastName": "Lovelace",
    "phoneNumber": "+4915112345678",
    "timezoneIana": "Europe/Berlin",
    "email": "[email protected]",
    "createdAt": "2026-03-13T09:00:00.000Z",
    "updatedAt": "2026-03-13T09:00:00.000Z",
    "properties": [
      {
        "key": "appointment_type",
        "value": "demo",
        "dataType": "select",
        "label": "Appointment Type"
      }
    ]
  },
  // Veraltetes Legacy-Feld, bleibt aus Gründen der Rückwärtskompatibilität erhalten.
  "contact_id": "telli contact identifier",
  // Veraltetes Legacy-Feld, bleibt aus Gründen der Rückwärtskompatibilität erhalten.
  "external_contact_id": "your contact identifier",
  // Veraltetes Legacy-Feld, bleibt aus Gründen der Rückwärtskompatibilität erhalten.
  "contact_details": {
    "foobar": "baz"
  }
}

{
  "available": [
    {
      "start_iso": "2024-01-01T10:00:00.000",
      "end_iso": "2024-01-01T10:30:00.000"
    }
  ]
}

​
Termin buchen

Dieser Endpoint verarbeitet die eigentliche Buchung des ausgewählten Terminslots. 
POST /book

{
  "contact": {
    "id": "telli contact identifier",
    "type": "Contact",
    "externalId": "your contact identifier",
    "externalUrl": null,
    "salutation": null,
    "firstName": "Ada",
    "lastName": "Lovelace",
    "phoneNumber": "+4915112345678",
    "timezoneIana": "Europe/Berlin",
    "email": "[email protected]",
    "createdAt": "2026-03-13T09:00:00.000Z",
    "updatedAt": "2026-03-13T09:00:00.000Z",
    "properties": [
      {
        "key": "appointment_type",
        "value": "demo",
        "dataType": "select",
        "label": "Appointment Type"
      }
    ]
  },
  // Veraltetes Legacy-Feld, bleibt aus Gründen der Rückwärtskompatibilität erhalten.
  "contact_id": "telli contact identifier",
  // Veraltetes Legacy-Feld, bleibt aus Gründen der Rückwärtskompatibilität erhalten.
  "external_contact_id": "your contact identifier",
  "start_iso": "2024-01-01T10:00:00.000",
  // Veraltetes Legacy-Feld, bleibt aus Gründen der Rückwärtskompatibilität erhalten.
  "contact_details": {
    "foobar": "baz"
  }
}

{
  "status": "success"
}

{
  "status": "failed",
  "reason": "Appointment slot is no longer available"
}

​
Hinweise zur Umsetzung

  • contact ist das bevorzugte Feld für Kontaktdaten und folgt dem V2-Kontaktformat inklusive typisierter properties
  • contact_id, external_contact_id und contact_details sind veraltete Legacy-Felder, die aus Gründen der Rückwärtskompatibilität weiterhin mitgesendet werden
  • contact_details enthält die frühere flache Key-Value-Struktur aus den V1-Dynamic-Variables
  • Nutze UTC-Zeitstempel im ISO-8601-Format
  • telli verwendet start_iso als Kennung des Slots
  • Gib HTTP-200-Antworten zurück und signalisiere Erfolg oder Fehler im Response-Body
  • Stelle sicher, dass telli deine Endpunkte erreichen kann

​
Request-Authentifizierung

Wenn du Requests von telli prüfen willst, verifiziere den Header x-telli-signature. 
const crypto = require("crypto");

function verifyRequest(payload, signature, apiKey) {
  const expectedSignature = crypto
    .createHmac("sha256", apiKey)
    .update(JSON.stringify(payload))
    .digest("hex");

  return signature === expectedSignature;
}

​
Verwandte Seiten