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
Twilio	Telefonnummern und Anrufe	Verfügbar
API Keys	Zugang für externe Anwendungen	Verfügbar
Webhooks	Echtzeit-Ereignisbenachrichtigungen	Verfügbar
Google Calendar	Terminplanung	Verfügbar
Microsoft Outlook	Terminplanung	Verfügbar
Cal.com	Terminplanung	Verfügbar
CRM-Systeme	Kundendaten	Bald verfügbar

---

Twilio-Integration

Twilio stellt die Telefoninfrastruktur für Sprachanrufe bereit.

Einrichtungsschritte

1. Twilio-Konto erstellen (falls noch nicht vorhanden)

   • Gehen Sie zu twilio.com
   • Registrieren Sie sich für ein Konto
   • Vervollständigen Sie die Verifizierung

2. Anmeldedaten erhalten

   • Melden Sie sich bei der Twilio-Konsole an
   • Kopieren Sie die Account SID
   • Kopieren Sie den Auth Token

3. Mit Hanc.AI verbinden

   • Gehen Sie zu Integration → Twilio
   • Geben Sie die Account SID ein
   • Geben Sie den Auth Token ein
   • Klicken Sie auf Connect

4. Nummern importieren

   • Nach der Verbindung erscheinen Ihre Twilio-Nummern
   • Klicken Sie auf Import, um sie zu Hanc.AI hinzuzufügen
   • Weisen Sie Agenten zu Nummern zu

Twilio-Konfiguration

┌─────────────────────────────────────────────────────────────────┐
│                  TWILIO-INTEGRATION                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Account SID:  AC________________________________               │
│                                                                 │
│  Auth Token:   ________________________________                 │
│                                                                 │
│  Status:       ● Verbunden                                      │
│                                                                 │
│  [Trennen]  [Nummern aktualisieren]                             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Twilio-Fehlerbehebung

Problem	Lösung
Verbindung schlägt fehl	Anmeldedaten überprüfen
Nummern erscheinen nicht	„Nummern aktualisieren" klicken
Anrufe werden nicht geroutet	Nummern-Webhook in Twilio prüfen

---

API Keys

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

API-Schlüssel 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 (lesen, schreiben, 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/agents" \
  -H "Authorization: Bearer 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

---

Webhooks

Webhooks senden Echtzeit-Benachrichtigungen, wenn Ereignisse auftreten.

Webhooks einrichten

1. Gehen Sie zu Integration → Webhooks
2. Klicken Sie auf „Add Webhook"
3. Geben Sie Ihre Endpoint-URL ein
4. Wählen Sie auslösende Ereignisse
5. Speichern und testen

Verfügbare Ereignisse

Ereignis	Auslöser	Payload enthält
call.started	Anruf beginnt	Agent-ID, Anrufernummer
call.ended	Anruf beendet	Dauer, Transkript, Stimmung
call.transferred	Weiterleitung an Menschen	Grund, Ziel
appointment.created	Buchung erstellt	Datum, Uhrzeit, Kundeninfo
appointment.cancelled	Buchung storniert	Grund, Kundeninfo

Webhook-Payload-Beispiel

{
  "event": "call.ended",
  "timestamp": "2024-01-15T14:30:00Z",
  "data": {
    "call_id": "call_abc123",
    "agent_id": "agent_xyz789",
    "duration_seconds": 185,
    "caller_number": "+43664123456",
    "sentiment": "positive",
    "transcript": "...",
    "escalated": false
  }
}

Webhook-Sicherheit

Webhook-Signaturen validieren:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return signature === expected;
}

---

Kalender-Integrationen

Verbinden Sie Kalender für Terminbuchungen.

Google Calendar

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
5. Wählen Sie zu synchronisierende Kalender

Angeforderte Berechtigungen:

• Kalendertermine anzeigen
• Kalendertermine erstellen
• Kalendertermine ändern

Microsoft Outlook

1. Gehen Sie zu Integration → Calendars
2. Klicken Sie auf „Connect Outlook"
3. Melden Sie sich mit Microsoft an
4. Autorisieren Sie Zugang
5. Wählen Sie Kalender

Cal.com

1. Gehen Sie zu Integration → Calendars
2. Klicken Sie auf „Connect Cal.com"
3. Geben Sie den API-Schlüssel von Cal.com ein
4. Konfigurieren Sie Eventtypen

Kalendernutzung in Agenten

Nach der Verbindung können Agenten:

• Verfügbarkeit für bestimmte Zeiten prüfen
• Termine automatisch buchen
• Kalendereinladungen senden
• Umbuchungen 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?"

---

CRM-Integration (Bald verfügbar)

Verbindung zu Customer-Relationship-Management-Systemen:

Geplante CRMs

• HubSpot
• Salesforce
• Pipedrive
• Zoho CRM

Geplante Funktionen

• Automatische Anrufprotokollierung
• Kundendaten-Abruf
• Lead-Erstellung
• Aktivitätsverfolgung

---

Benutzerdefinierte Integrationen

API verwenden

Erstellen Sie benutzerdefinierte Integrationen mit der Hanc.AI API:

Basis-URL: https://api.hanc.ai/v1
Authentifizierung: Bearer Token (API-Schlüssel)
Format: JSON

API-Dokumentation

Verfügbare Endpoints:

Endpoint	Methode	Zweck
/agents	GET	Alle Agenten auflisten
/agents/{id}	GET	Agent-Details abrufen
/agents	POST	Agent erstellen
/calls	GET	Anrufprotokolle auflisten
/calls/{id}	GET	Anrufdetails abrufen
/knowledge-bases	GET	Wissensdatenbanken auflisten
/knowledge-bases	POST	Wissensdatenbank erstellen

Beispiel: Agent per API erstellen

curl -X POST "https://api.hanc.ai/v1/agents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support-Agent",
    "first_message": "Hallo, wie kann ich Ihnen helfen?",
    "prompt": "Du bist ein hilfreicher Support-Agent...",
    "language": "de",
    "provider": "openai",
    "model": "gpt-4o"
  }'

---

Integrations-Best-Practices

Sicherheit

✅ HTTPS für alle Webhooks verwenden ✅ Anmeldedaten sicher speichern ✅ API-Schlüssel regelmäßig rotieren ✅ Berechtigungen auf Minimum beschränken

Zuverlässigkeit

✅ Webhook-Fehler graceful behandeln ✅ Retry-Logik implementieren ✅ 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

Webhooks empfangen keine Ereignisse

1. URL ist öffentlich zugänglich
2. URL gibt Status 200 zurück
3. Webhook-Logs im Dashboard prüfen
4. Mit webhook.site zum Debuggen testen

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 — Twilio-Nummernverwaltung
• Sprachagenten — Integrationen in Agenten nutzen
• Analytik — Integrationsereignis-Tracking