Skip to main content

​
HubSpot Kontakt-Abruf Template

Dieses Template ermöglicht es Ihrem KI-Assistenten, während eines Gesprächs automatisch Kontaktdaten aus HubSpot abzurufen. Sobald ein Kunde seine E-Mail-Adresse nennt, werden die relevanten Informationen sofort verfügbar gemacht.

​
Überblick

Funktionsweise

  • Kunde nennt E-Mail-Adresse im Gespräch
  • Automatische Extraktion der E-Mail durch KI
  • Echtzeit-Abfrage bei HubSpot CRM
  • Sofortige Personalisierung der Antworten

Typische Anwendung

  • Kundenverifizierung bei Support-Anfragen
  • Personalisierte Begrüßung und Ansprache
  • Kontextualisierte Gesprächsführung
  • Automatische Gesprächsprotokollierung

​
Schritt-für-Schritt-Konfiguration

​
1. HubSpot API-Key beschaffen

1

HubSpot Dashboard öffnen

  • Melden Sie sich in Ihrem HubSpot-Account an
  • Navigieren Sie zu “Einstellungen” (⚙️)
2

API-Key generieren

  • Gehen Sie zu “Integrationen” → “Private Apps”
  • Klicken Sie auf “Create a private app”
  • Vergeben Sie einen aussagekräftigen Namen (z.B. “Famulor Mid-Call Tools”)
3

Berechtigungen konfigurieren

Erforderliche Scopes:
  - crm.objects.contacts.read
  - crm.objects.companies.read (optional)
  - crm.objects.deals.read (optional)
4

API-Key sichern

  • Kopieren Sie den generierten API-Key
  • Speichern Sie ihn sicher (wird für die Tool-Konfiguration benötigt)

​
2. Mid-Call-Tool konfigurieren

​
Grundlegende Tool-Einstellungen

  • Funktions-Details
  • URL & Authentication
FeldWertBeschreibung
Funktionsnameget_hubspot_contactEindeutiger Identifier ohne Leerzeichen
Beschreibung”Ruft einen Kontakt aus HubSpot anhand der E-Mail-Adresse ab. Verwenden Sie diese Funktion, wenn der Kunde seine E-Mail-Adresse nennt, um personalisierte Informationen zu erhalten.”Agent-Anweisungen
HTTP-MethodeGETDaten abrufen (Read-Only)
Timeout5000Millisekunden (5 Sekunden)

​
Detaillierte Konfiguration

Basis-URL: https://api.hubapi.com/crm/v3/objects/contacts/{email}
  • {email} wird automatisch durch den Parameter ersetzt
  • Unterstützt auch andere Identifier wie {contact_id} oder {phone}
Alternative URLs für verschiedene Lookup-Methoden:
E-Mail-basiert: /crm/v3/objects/contacts/{email}
ID-basiert: /crm/v3/objects/contacts/{contact_id}
Telefon-basiert: /crm/v3/objects/contacts/{phone}
Authentifizierung:
{
  "Authorization": "Bearer IHRE_HUBSPOT_API_KEY",
  "Content-Type": "application/json",
  "User-Agent": "Famulor-MidCall-Tool/1.0"
}
Sicherheitshinweis: Verwenden Sie Umgebungsvariablen für API-Keys. Niemals API-Keys direkt im Code speichern!
Standard-Parameter:
idProperty: "email"  # Lookup-Feld spezifizieren
properties: "firstname,lastname,company,phone,lastmodifieddate,lifecyclestage"
Erweiterte Properties (optional):
# Für umfangreichere Datenabfrage
properties: "firstname,lastname,email,phone,company,jobtitle,
             lastmodifieddate,lifecyclestage,hs_lead_status,
             createdate,notes_last_updated,num_notes"

# Für Performance-optimierte Abfrage (minimal)
properties: "firstname,lastname,company"
Associations (für verwandte Objekte):
associations: "companies,deals"  # Lädt auch Firmen- und Deal-Daten

​
3. Parameter-Schema definieren

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "E-Mail-Adresse des Kontakts, den Sie in HubSpot nachschlagen möchten",
      "format": "email"
    }
  },
  "required": ["email"]
}

​
4. Erweiterte Parameter-Optionen

  • Flexible Lookup
  • Mit Filteroptionen
{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "E-Mail-Adresse des Kontakts"
    },
    "contact_id": {
      "type": "string", 
      "description": "HubSpot Kontakt-ID (alternativ zur E-Mail)"
    },
    "phone": {
      "type": "string",
      "description": "Telefonnummer des Kontakts (alternativ)"
    }
  },
  "oneOf": [
    {"required": ["email"]},
    {"required": ["contact_id"]},
    {"required": ["phone"]}
  ]
}

​
Response-Verarbeitung

​
Typische API-Antwort

{
  "id": "12345",
  "properties": {
    "firstname": "Max",
    "lastname": "Mustermann",
    "email": "max.mustermann@beispiel.de",
    "phone": "+49 123 456789",
    "company": "Beispiel GmbH",
    "jobtitle": "Geschäftsführer",
    "lifecyclestage": "customer",
    "createdate": "2024-01-01T10:00:00.000Z",
    "lastmodifieddate": "2024-01-15T10:30:00.000Z",
    "hs_lead_status": "CONNECTED"
  },
  "createdAt": "2024-01-01T10:00:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

​
KI-Integration und Sprachanpassungen

​
Natürliche Sprachverwendung

Der KI-Assistent kann die abgerufenen Daten wie folgt verwenden:
Beispiele für natürliche Integration:
  • “Hallo Herr Mustermann! Ich sehe, Sie sind Geschäftsführer der Beispiel GmbH.”
  • “Schön, Sie wieder zu sprechen, Max. Wie geht es denn der Beispiel GmbH?”
  • “Perfekt, ich habe Ihre Daten gefunden. Sie sind seit Januar 2024 bei uns im System.”
Basierend auf Lifecycle-Stage:
Wenn lifecyclestage == "lead":
  "Ich sehe, Sie interessieren sich für unsere Services. Wie kann ich Ihnen helfen?"

Wenn lifecyclestage == "customer":
  "Als bestehender Kunde haben Sie natürlich Vorrang. Was kann ich für Sie tun?"

Wenn lifecyclestage == "opportunity":
  "Ich sehe, wir sind bereits im Gespräch über eine mögliche Zusammenarbeit..."
Lead-Status-basierte Ansprache:
hs_lead_status:
  "NEW": "Vielen Dank für Ihr Interesse! Lassen Sie mich Ihnen gerne weiterhelfen."
  "ATTEMPTED_TO_CONTACT": "Schön, dass Sie sich melden! Wir haben versucht, Sie zu erreichen."
  "CONNECTED": "Perfekt, wir hatten ja schon Kontakt. Wie kann ich Ihnen heute helfen?"
  "BAD_TIMING": "Kein Problem, dass es beim letzten Mal nicht gepasst hat."

​
Fehlerbehandlung

​
Häufige Fehlerszenarien

  • 404 - Kontakt nicht gefunden
  • 401 - Authentifizierungsfehler
  • 429 - Rate Limit erreicht
  • Timeout-Behandlung
Ursache: E-Mail-Adresse existiert nicht in HubSpotGraceful Fallback:
Antwort: "Ich kann Ihre E-Mail-Adresse leider nicht in unserem System finden. 
         Möchten Sie mir eine alternative E-Mail-Adresse geben oder 
         soll ich ein neues Kundenprofil für Sie anlegen?"

Nächste Schritte:
  - Alternative E-Mail erfragen
  - Lead-Erstellung anbieten
  - Manuellen Support einschalten

​
Testing und Validierung

​
Automatische Tests

1

API-Konnektivität testen

Das System führt automatisch Tests mit Standard-Testwerten durch:
2

Performance-Monitoring

Überwachung kritischer Metriken:
  • Response Time: <3 Sekunden (Ziel)
  • Success Rate: >95%
  • Error Rate: <5%

​
Manuelle Tests

Positive Test-Fälle:
  • Bekannte E-Mail-Adresse → Korrekte Datenrückgabe
  • Korrekte Datenformatierung in der Antwort
  • Angemessene Response-Zeit (<5 Sekunden)
  • Natürliche Sprachintegration
Negative Test-Fälle:
  • Unbekannte E-Mail → Graceful 404-Behandlung
  • Ungültige E-Mail-Format → Sinnvolle Fehlermeldung
  • API-Timeout → Fallback-Verhalten
  • Netzwerkfehler → Angemessene Benutzerinformation
Realistische Szenarien testen:
  1. Standard-Kundenkontakt:
    • Kunde: “Meine E-Mail ist max@beispiel.de”
    • Erwartete KI-Reaktion: Personalisierte Begrüßung mit Namen und Firma
  2. Unbekannter Kontakt:
  3. Performance-Test:
    • Mehrere schnelle Abfragen hintereinander
    • Erwartetes Verhalten: Konstante Performance ohne Degradation

​
Erweiterte Konfigurationen

​
Multi-Property Lookup

Für komplexere Szenarien:
URL: https://api.hubapi.com/crm/v3/objects/contacts/search

POST Body:
{
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "email",
          "operator": "EQ", 
          "value": "{email}"
        }
      ]
    }
  ],
  "properties": ["firstname", "lastname", "company", "phone", "lifecyclestage"],
  "limit": 1
}

​
Caching-Optimierung

  • Session-basiertes Caching
  • Time-based Cache
Caching-Strategie:
  Dauer: Bis Gesprächsende
  Zweck: Vermeidung wiederholter API-Calls im gleichen Gespräch
  Implementation: Automatisch durch Famulor-System

​
Integration mit anderen Tools

​
Workflow-Kombination

​
Best Practices

​
Performance-Optimierung

Selective Properties

Nur notwendige Daten abrufen:
  • Standard: firstname, lastname, company
  • Bei Bedarf: jobtitle, lifecyclestage
  • Vermeiden: notes, alle custom properties

Timeout-Management

Angemessene Timeout-Werte:
  • Standard: 5 Sekunden
  • Critical Calls: 3 Sekunden
  • Batch Operations: 10 Sekunden

​
Sicherheit und Compliance

Datenschutz-Maßnahmen:
  • Minimale Datenabfrage (nur erforderliche Properties)
  • Keine Speicherung sensibler Daten über Gesprächsende hinaus
  • Audit-Logging aller Datenzugriffe
  • Opt-out-Mechanismen für Kunden
Sicherheits-Best-Practices:
  • API-Keys in Umgebungsvariablen speichern
  • Regelmäßige Key-Rotation (quartalsweise)
  • IP-Whitelisting wenn möglich
  • SSL/TLS für alle Verbindungen

​
Monitoring und Analytics

​
Key Performance Indicators

MetrikZielwertKritischer Wert
Success Rate>98%<90%
Average Response Time<2s>5s
Error Rate<2%>10%
Customer Satisfaction>4.5/5<4.0/5

​
Troubleshooting Guide

1

Häufige Probleme identifizieren

  • API-Key-Ablauf (401 Errors)
  • Rate-Limiting (429 Errors)
  • Netzwerk-Timeouts
  • Falsche URL-Parameter
2

Monitoring einrichten

  • Automatische Alerts bei >5% Error Rate
  • Daily Performance Reports
  • Weekly Usage Analytics
3

Kontinuierliche Optimierung

  • Monatliche Performance-Reviews
  • Quarterly API-Integration-Updates
  • Customer Feedback Integration

Nächste Schritte

Nachdem Sie das HubSpot Kontakt-Abruf-Tool implementiert haben, können Sie weitere HubSpot-Integrationen hinzufügen:
Wichtiger Hinweis: Testen Sie die Integration zunächst in einer Entwicklungsumgebung, bevor Sie sie in der Produktion einsetzen. Überwachen Sie die Performance kontinuierlich und implementieren Sie entsprechende Fallback-Mechanismen.