HubSpot Kontakt-Abruf Template

Dieses Template ermöglicht es deinem 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

HubSpot Dashboard öffnen

Melde dich in deinem HubSpot-Account an
Navigiere zu “Einstellungen” (⚙️)

API-Key generieren

Geh zu “Integrationen” → “Private Apps”
Klicke auf “Create a private app”
Vergib einen aussagekräftigen Namen (z.B. “Famulor Mid-call Actions”)

Berechtigungen konfigurieren

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

API-Key sichern

Kopiere den generierten API-Key
Speichere ihn sicher (wird für die Tool-Konfiguration benötigt)

2. Mid-call Action konfigurieren

Grundlegende Tool-Einstellungen

Funktions-Details
URL & Authentication

Feld	Wert	Beschreibung
Funktionsname	`get_hubspot_contact`	Eindeutiger 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-Methode	`GET`	Daten abrufen (Read-Only)
Timeout	`5000`	Millisekunden (5 Sekunden)

URL:
  https://api.hubapi.com/crm/v3/objects/contacts/{email}

Headers:
  Authorization: "Bearer IHRE_HUBSPOT_API_KEY"
  Content-Type: "application/json"

Query Parameters:
  idProperty: "email"
  properties: "firstname,lastname,company,phone,lastmodifieddate,lifecyclestage"

Detaillierte Konfiguration

URL-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}

Header-Konfiguration

Authentifizierung:

{
  "Authorization": "Bearer IHRE_HUBSPOT_API_KEY",
  "Content-Type": "application/json",
  "User-Agent": "Famulor-MidCall-Action/1.0"
}

Sicherheitshinweis: Verwende Umgebungsvariablen für API-Keys. Niemals API-Keys direkt im Code speichern!

Query Parameter

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"]}
  ]
}

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "E-Mail-Adresse des Kontakts"
    },
    "include_deals": {
      "type": "boolean",
      "description": "Sollen auch verknüpfte Deals abgerufen werden?",
      "default": false
    },
    "include_companies": {
      "type": "boolean", 
      "description": "Sollen auch Unternehmensdaten abgerufen werden?",
      "default": true
    }
  },
  "required": ["email"]
}

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:

Personalisierte Begrüßung

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.”

Kontextuelle Gesprächsführung

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..."

Automatische Qualifizierung

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

Ursache: API-Key ungültig oder abgelaufenSystemreaktion:

Intern: Fehlerprotokollierung für Admin
Kunde: "Entschuldigung, ich habe momentan ein technisches Problem 
        beim Zugriff auf unsere Kundendatenbank. Kann ich Ihnen 
        trotzdem weiterhelfen?"

Escalation: Benachrichtigung an Technical Team

Ursache: Zu viele API-Anfragen in kurzer ZeitHandhabung:

Retry-Logik: Automatischer Wiederholungsversuch nach 1-2 Sekunden
Fallback: "Einen Moment bitte, ich rufe Ihre Daten ab..."

Wenn weiterhin fehlschlagend:
  "Es tut mir leid, unser System ist momentan ausgelastet. 
   Darf ich Ihre Anfrage manuell bearbeiten?"

Ursache: API-Antwort dauert länger als 5 SekundenGraceful Degradation:

Nach 3 Sekunden: "Einen Moment, ich schaue in unserem System nach..."
Nach 5 Sekunden: "Die Datenabfrage dauert etwas länger als gewöhnlich..."
Nach 8 Sekunden: "Entschuldigung für die Verzögerung. Können Sie mir 
                  Ihren Namen nennen, damit ich Ihnen trotzdem helfen kann?"

Testing und Validierung

Automatische Tests

API-Konnektivität testen

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

E-Mail: “test@example.com”
Erwartetes Verhalten: 404 oder Kontaktdaten

Performance-Monitoring

Überwachung kritischer Metriken:

Response Time: <3 Sekunden (Ziel)
Success Rate: >95%
Error Rate: <5%

Manuelle Tests

Funktionstest-Checkliste

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

Gesprächsfluss-Tests

Realistische Szenarien testen:

Standard-Kundenkontakt:
- Kunde: “Meine E-Mail ist max@beispiel.de”
- Erwartete KI-Reaktion: Personalisierte Begrüßung mit Namen und Firma
Unbekannter Kontakt:
- Kunde: “test12345@nichthierregistriert.de”
- Erwartete KI-Reaktion: Höfliche Nachfrage nach alternativer E-Mail
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

Für häufig abgefragte Kontakte:
  Cache-Dauer: 5 Minuten
  Aktualisierung: Bei bekannten Datenänderungen
  Fallback: Frische Datenabfrage bei Cache-Miss

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

DSGVO-Konformität

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

API-Security

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

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

Troubleshooting Guide

Häufige Probleme identifizieren

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

Monitoring einrichten

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

Kontinuierliche Optimierung

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

Nächste Schritte

Nachdem du das HubSpot Kontakt-Abruf-Tool implementiert hast, kannst du weitere HubSpot-Integrationen hinzufügen:

Deal-Management Tool
Lead-Erstellung Tool
Webhook-Integration für komplexere Workflows

Wichtiger Hinweis: Teste die Integration zunächst in einer Entwicklungsumgebung, bevor du sie in der Produktion einsetzt. Überwache die Performance kontinuierlich und implementiere entsprechende Fallback-Mechanismen.

Statt einzelner HTTP-Aktionen ein ganzes Toolset auf einmal? Externen MCP-Server verbinden — Tools werden automatisch erkannt. Siehe MCP-Server.

Mid-Call-Tools

Mid-Call-Tools Integrationen

HubSpot Kontakt-Abruf

HubSpot Kontakt-Abruf Template

Überblick

Funktionsweise

Typische Anwendung

Schritt-für-Schritt-Konfiguration

1. HubSpot API-Key beschaffen

2. Mid-call Action konfigurieren

Grundlegende Tool-Einstellungen

Detaillierte Konfiguration

3. Parameter-Schema definieren

4. Erweiterte Parameter-Optionen

Response-Verarbeitung

Typische API-Antwort

KI-Integration und Sprachanpassungen

Natürliche Sprachverwendung

Fehlerbehandlung

Häufige Fehlerszenarien

Testing und Validierung

Automatische Tests

Manuelle Tests

Erweiterte Konfigurationen

Multi-Property Lookup

Caching-Optimierung

Integration mit anderen Tools

Workflow-Kombination

Best Practices

Performance-Optimierung

Selective Properties

Timeout-Management

Sicherheit und Compliance

Monitoring und Analytics

Key Performance Indicators

Troubleshooting Guide

Nächste Schritte

​HubSpot Kontakt-Abruf Template

​Überblick

Funktionsweise

Typische Anwendung

​Schritt-für-Schritt-Konfiguration

​1. HubSpot API-Key beschaffen

​2. Mid-call Action konfigurieren

​Grundlegende Tool-Einstellungen

​Detaillierte Konfiguration

​3. Parameter-Schema definieren

​4. Erweiterte Parameter-Optionen

​Response-Verarbeitung

​Typische API-Antwort

​KI-Integration und Sprachanpassungen

​Natürliche Sprachverwendung

​Fehlerbehandlung

​Häufige Fehlerszenarien

​Testing und Validierung

​Automatische Tests

​Manuelle Tests

​Erweiterte Konfigurationen

​Multi-Property Lookup

​Caching-Optimierung

​Integration mit anderen Tools

​Workflow-Kombination

​Best Practices

​Performance-Optimierung

Selective Properties

Timeout-Management

​Sicherheit und Compliance

​Monitoring und Analytics

​Key Performance Indicators

​Troubleshooting Guide

Nächste Schritte

HubSpot Kontakt-Abruf Template

Überblick

Schritt-für-Schritt-Konfiguration

1. HubSpot API-Key beschaffen

2. Mid-call Action konfigurieren

Grundlegende Tool-Einstellungen

Detaillierte Konfiguration

3. Parameter-Schema definieren

4. Erweiterte Parameter-Optionen

Response-Verarbeitung

Typische API-Antwort

KI-Integration und Sprachanpassungen

Natürliche Sprachverwendung

Fehlerbehandlung

Häufige Fehlerszenarien

Testing und Validierung

Automatische Tests

Manuelle Tests

Erweiterte Konfigurationen

Multi-Property Lookup

Caching-Optimierung

Integration mit anderen Tools

Workflow-Kombination

Best Practices

Performance-Optimierung

Sicherheit und Compliance

Monitoring und Analytics

Key Performance Indicators

Troubleshooting Guide