Integrationen

Integrationen erweitern Ihre Sprachagenten durch Verbindung mit externen Diensten. Dieser Abschnitt behandelt alle verfügbaren Integrationen und deren Konfiguration.

Verfügbare Integrationen

Integration	Zweck	Status	Pläne
Telefonnummern	Telefonnummern und Anrufe	Verfügbar	Alle
SIP Trunk	Bestehende Telefoninfrastruktur verbinden	Verfügbar	Alle
Google Calendar	Terminplanung	Verfügbar	Alle
API Keys	Zugang für externe Anwendungen	Verfügbar	Alle
Webhooks	Echtzeit-Ereignisbenachrichtigungen	Verfügbar	Alle

Alle Pläne

Kalender-Integrationen, SIP, API-Zugang und Webhooks sind in allen Plänen verfügbar, einschließlich Free.

---

Telefonnummern-Einrichtung

Telefonnummern ermöglichen es Ihren Agenten, echte Telefonanrufe zu empfangen und zu tätigen.

Einrichtungsschritte

1. Gehen Sie zu Phone Numbers in der Seitenleiste
2. Klicken Sie auf "Buy Number"
3. Wählen Sie Land und Nummerntyp
4. Schließen Sie den Kauf ab
5. Weisen Sie einen Agenten der Nummer zu

Nummern werden nach dem Kauf automatisch konfiguriert und sind einsatzbereit.

---

SIP-Trunk-Integration

Verbinden Sie Ihren bestehenden SIP-Trunk-Anbieter, um Anrufe über Hanc.AI-Sprachagenten zu leiten. Verfügbar in allen Plänen einschließlich Free.

Einrichtungsschritte

1. Gehen Sie zu Phone Numbers in der Seitenleiste
2. Klicken Sie auf "Connect SIP"
3. Geben Sie Ihre SIP-Trunk-Anmeldedaten ein:
   • SIP Server / Domain -- die SIP-Adresse Ihres Anbieters
   • Username -- Ihr SIP-Konto-Benutzername
   • Password -- Ihr SIP-Konto-Passwort
   • Port -- SIP-Port (Standard: 5060)
4. Klicken Sie auf Connect
5. Weisen Sie einen Agenten zu, der Anrufe von diesem Trunk bearbeitet

Wann SIP verwenden

Szenario	Empfehlung
Neu bei Telefondiensten	Nummern über Hanc.AI kaufen (einfachere Einrichtung)
Bestehendes PBX-System	SIP-Trunk zur Integration nutzen
Enterprise-Telefonie	SIP-Trunk für volle Kontrolle
Mehrere Anbieter	SIP für Flexibilität

---

Google Calendar-Integration

Verbinden Sie Google Calendar, um Ihren Sprachagenten die Verfügbarkeitsprüfung und Terminbuchung während Anrufen zu ermöglichen.

Einrichtungsschritte

1. Gehen Sie zu Integration > Calendars
2. Klicken Sie auf "Connect Google Calendar"
3. Melden Sie sich mit Google an
4. Autorisieren Sie Hanc.AI-Zugang

Angeforderte Berechtigungen:

• Kalendertermine anzeigen (um Verfügbarkeit zu prüfen)
• Kalendertermine erstellen (um Termine zu buchen)

Kalender-Konfiguration

Nach der Verbindung konfigurieren Sie das Kalender-Tool an Ihrem Agenten:

Einstellung	Beschreibung
calendar_id	Welcher Google Calendar für die Terminplanung verwendet wird
timezone	Zeitzone für die Terminplanung (z.B. Europe/Vienna)
work_hours	Verfügbare Stunden für Buchungen (z.B. Montag-Freitag 9:00-18:00)
slot_duration	Standard-Terminlänge (z.B. 30 Minuten)
buffer	Pufferzeit zwischen Terminen (z.B. 15 Minuten)

Kalendernutzung in Agenten

Nach Verbindung und Konfiguration können Agenten:

• Verfügbarkeit für bestimmte Daten und Zeiten prüfen
• Termine automatisch buchen
• Arbeitszeiten und Pufferzeiten berücksichtigen
• Umbuchungsanfragen bearbeiten

Beispielgespräch:

Kunde: "Kann ich einen Termin für Dienstag um 15 Uhr buchen?"

Agent: [Prüft Kalender]
       "Ja, Dienstag um 15 Uhr ist verfügbar.
        Darf ich Ihren Namen für die Buchung haben?"

---

API Keys

Generieren Sie API-Schlüssel, um Hanc.AI in Ihre eigenen Anwendungen zu integrieren.

API-Schlüssel erstellen

Sie können bis zu 3 API-Schlüssel pro Benutzer erstellen.

1. Gehen Sie zu Integration > API Keys
2. Klicken Sie auf "Create API Key"
3. Geben Sie einen Namen ein (z.B. "CRM-Integration")
4. Legen Sie Berechtigungen fest (read, write, admin)
5. Kopieren Sie den Schlüssel sofort (wird nur einmal angezeigt)

API-Schlüssel-Sicherheit

Wichtig

• Schlüssel sicher speichern (Umgebungsvariablen, Secrets Manager)
• Schlüssel niemals in Versionskontrolle committen
• Schlüssel regelmäßig rotieren
• Unbenutzte Schlüssel löschen

API-Schlüssel verwenden

In API-Anfragen einbinden:

curl -X GET "https://api.hanc.ai/v1/agent/list" \
  -H "x-api-key: YOUR_API_KEY"

API-Schlüssel-Berechtigungen

Berechtigung	Zugang
Read	Agenten, Anrufe, Analytik anzeigen
Write	Agenten erstellen/ändern, KB hochladen
Admin	Alle Operationen, löschen, Einstellungen

Verfügbare API-Endpunkte

Basis-URL	https://api.hanc.ai
Authentifizierung	API-Schlüssel via x-api-key Header
Format	JSON

Anrufe

Aktion	Methode	Endpunkt
Anrufe auflisten	GET	/v1/call/list
Anrufdetails (Transkript, Sentiment, Zusammenfassung)	GET	/v1/call/:id
Allgemeine Analytik (Metriken nach Datum/Agent)	GET	/v1/call/general-metrics
Tägliche Analytik	GET	/v1/call/daily-metrics
Sentiment-Statistiken	GET	/v1/call/sentiment-stats
Kostenaufschlüsselung	GET	/v1/call/costs-breakdown
Anrufe exportieren (CSV)	GET	/v1/call/list/export
Kosten exportieren (CSV)	GET	/v1/call/costs-breakdown/export
Telefonanruf tätigen	POST	/v1/call/make-phone-call
Webanruf tätigen	POST	/v1/call/make-web-call

Agenten

Aktion	Methode	Endpunkt
Agenten auflisten	GET	/v1/agent/list
Agentendetails	GET	/v1/agent/:id
Agent erstellen	POST	/v1/agent
Agent aktualisieren	PATCH	/v1/agent/:id
Agent löschen	DELETE	/v1/agent/:id
Anrufstatistiken des Agenten	GET	/v1/agent/:id/call-stats
Agentenvorlagen auflisten	GET	/v1/agent/agent_template/list

Agenten-Aktionen:

Aktion	Methode	Endpunkt
Aktionen auflisten	GET	/v1/agent/:id/actions
Aktion hinzufügen	POST	/v1/agent/:id/actions
Aktion aktualisieren	PATCH	/v1/agent/:id/actions/:actionId
Aktion löschen	DELETE	/v1/agent/:id/actions/:actionId

Agenten-Tools:

Aktion	Methode	Endpunkt
Tools auflisten	GET	/v1/agent/:id/tools
Tool hinzufügen	POST	/v1/agent/:id/tools
Tool aktualisieren	PATCH	/v1/agent/:id/tools/:toolId
Tool löschen	DELETE	/v1/agent/:id/tools/:toolId

Wissensdatenbank

Aktion	Methode	Endpunkt
Wissensdatenbanken auflisten	GET	/v1/knowledge-base/list
Wissensdatenbank erstellen	POST	/v1/knowledge-base
Datei(en) hochladen	POST	/v1/knowledge-base/:id/file(s)
Datei löschen	DELETE	/v1/knowledge-base/:id/file
Agenten zuweisen	PUT	/v1/knowledge-base/:id/agents

Telefonnummern

Aktion	Methode	Endpunkt
Nummern auflisten	GET	/v1/phone-number/list
Verfügbare Nummern (nach Land)	GET	/v1/phone-number/available
Nummer kaufen	POST	/v1/phone-number/buy
Nummer importieren	POST	/v1/phone-number/import
Mit SIP verbinden	PATCH	/v1/phone-number/connect-to-sip

Stimmen

Aktion	Methode	Endpunkt
Stimmen auflisten	GET	/v1/voice/list

Nach Sprache filtern: GET /v1/voice/list?language=de

Abonnement

Aktion	Methode	Endpunkt
Abonnementdetails	GET	/v1/subscription
Auto-Aufladung konfigurieren	PATCH	/v1/subscription/auto-top-up
Aufladebetrag festlegen	PATCH	/v1/subscription/top-up-amount

Kunden

Aktion	Methode	Endpunkt
Kunden auflisten	GET	/v1/customer/list
Kundendetails	GET	/v1/customer/:id
Kunde erstellen	POST	/v1/customer
Kunde aktualisieren	PATCH	/v1/customer/:id
Kunde löschen	DELETE	/v1/customer/:id

Workspaces

Aktion	Methode	Endpunkt
Workspace-Operationen	GET/POST/PATCH/DELETE	/v1/workspaces/*
Mitglied einladen	POST	/v1/workspaces/:id/invite-member
Mitglied entfernen	DELETE	/v1/workspaces/:id/invite-member

Nicht über API verfügbar

Einige Operationen sind nur über das Dashboard verfügbar:

Funktion	Grund
API-Schlüssel-Verwaltung	Sicherheit -- Schlüssel können keine anderen Schlüssel erstellen
Telefonnummern-Einrichtung	Erfordert interaktive Einrichtung
Google Calendar-Integration	Erfordert interaktive Autorisierung
Abrechnung & Zahlungen	Wird über das Dashboard verwaltet

---

Webhooks

Konfigurieren Sie Webhooks, um Echtzeit-Benachrichtigungen über Ereignisse in Ihrem Hanc.AI-Konto zu erhalten.

Einrichtung

1. Gehen Sie zu Integration > Webhooks
2. Geben Sie Ihre Webhook-Endpoint-URL ein
3. Wählen Sie Ereignisse zum Abonnieren aus
4. Speichern Sie die Konfiguration

Webhooks senden HTTP-POST-Anfragen an Ihren Endpoint mit Ereignisdaten im JSON-Format.

---

Post-Call-Actions

Post-Call-Actions werden automatisch nach einem Sprachagenten-Gespräch ausgelöst. Konfigurieren Sie diese an einzelnen Agenten.

Verfügbare Action-Typen

Action	Beschreibung
Email	E-Mail-Zusammenfassung des Anrufs senden (an Geschäftsinhaber, Kunden oder beide)
SMS	SMS-Benachrichtigung nach dem Anruf senden
WhatsApp	WhatsApp-Nachricht nach dem Anruf senden
API Call	HTTP-Anfrage an einen externen Endpoint mit Anrufdaten senden

Einrichtung

1. Gehen Sie zu Voice Agents > wählen Sie Ihren Agenten
2. Öffnen Sie den Actions-Tab
3. Klicken Sie auf "Add Action"
4. Wählen Sie Action-Typ und konfigurieren Sie:
   • Trigger: Wann die Action ausgelöst wird (z.B. nach jedem Anruf, nur bei bestimmten Ergebnissen)
   • Recipients: Wer die Benachrichtigung erhält
   • Content: Nachrichtenvorlage mit Anrufdaten-Variablen

---

Benutzerdefinierte Integrationen

API verwenden

Erstellen Sie benutzerdefinierte Integrationen mit der Hanc.AI API:

Base URL: https://api.hanc.ai/v1
Authentication: Bearer token (API key)
Format: JSON

API-Dokumentation

Die vollständige Liste aller verfügbaren Endpoints finden Sie in der API-Referenz.

---

Integrations-Best-Practices

Sicherheit

• Anmeldedaten sicher speichern
• API-Schlüssel regelmäßig rotieren
• Berechtigungen auf Minimum beschränken

Zuverlässigkeit

• Alle Integrationsereignisse protokollieren
• Integrations-Gesundheit überwachen

Testen

• Integrationen zuerst im Staging testen
• Datenfluss in beide Richtungen verifizieren
• Fehlerszenarien testen
• Integrations-Setup dokumentieren

---

Fehlerbehebung

Integration verbindet sich nicht

1. Anmeldedaten auf Korrektheit prüfen
2. Auf Tippfehler prüfen
3. Sicherstellen, dass Drittanbieter-Konto aktiv ist
4. Versuchen, zu trennen und neu zu verbinden

Kalender synchronisiert nicht

1. Kalenderzugang neu autorisieren
2. Kalenderberechtigungen prüfen
3. Ausgewählten Kalender verifizieren
4. Auf Synchronisierungsverzögerungen prüfen (bis zu 5 Minuten)

---

Verwandte Themen

• Telefonnummern -- Telefonnummernverwaltung
• Sprachagenten -- Integrationen in Agenten nutzen
• Analytik -- Integrationsereignis-Tracking