> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# HubSpot Kontakt-Abruf

> Komplette Anleitung zur Implementierung eines HubSpot-Kontakt-Abruf-Tools für Mid-Call-Datenabfragen

# 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

<CardGroup cols={2}>
  <Card title="Funktionsweise" icon="gear">
    * Kunde nennt E-Mail-Adresse im Gespräch
    * Automatische Extraktion der E-Mail durch KI
    * Echtzeit-Abfrage bei HubSpot CRM
    * Sofortige Personalisierung der Antworten
  </Card>

  <Card title="Typische Anwendung" icon="phone">
    * Kundenverifizierung bei Support-Anfragen
    * Personalisierte Begrüßung und Ansprache
    * Kontextualisierte Gesprächsführung
    * Automatische Gesprächsprotokollierung
  </Card>
</CardGroup>

## Schritt-für-Schritt-Konfiguration

### 1. HubSpot API-Key beschaffen

<Steps>
  <Step title="HubSpot Dashboard öffnen">
    * Melde dich in deinem HubSpot-Account an
    * Navigiere zu "Einstellungen" (⚙️)
  </Step>

  <Step title="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")
  </Step>

  <Step title="Berechtigungen konfigurieren">
    ```yaml theme={null}
    Erforderliche Scopes:
      - crm.objects.contacts.read
      - crm.objects.companies.read (optional)
      - crm.objects.deals.read (optional)
    ```
  </Step>

  <Step title="API-Key sichern">
    * Kopiere den generierten API-Key
    * Speichere ihn sicher (wird für die Tool-Konfiguration benötigt)
  </Step>
</Steps>

### 2. Mid-call Action konfigurieren

#### Grundlegende Tool-Einstellungen

<Tabs>
  <Tab title="Funktions-Details">
    | 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)              |
  </Tab>

  <Tab title="URL & Authentication">
    ```yaml theme={null}
    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"
    ```
  </Tab>
</Tabs>

#### Detaillierte Konfiguration

<AccordionGroup>
  <Accordion title="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**:

    ```yaml theme={null}
    E-Mail-basiert: /crm/v3/objects/contacts/{email}
    ID-basiert: /crm/v3/objects/contacts/{contact_id}
    Telefon-basiert: /crm/v3/objects/contacts/{phone}
    ```
  </Accordion>

  <Accordion title="Header-Konfiguration">
    **Authentifizierung**:

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

    <Warning>
      **Sicherheitshinweis**: Verwende Umgebungsvariablen für API-Keys. Niemals API-Keys direkt im Code speichern!
    </Warning>
  </Accordion>

  <Accordion title="Query Parameter">
    **Standard-Parameter**:

    ```yaml theme={null}
    idProperty: "email"  # Lookup-Feld spezifizieren
    properties: "firstname,lastname,company,phone,lastmodifieddate,lifecyclestage"
    ```

    **Erweiterte Properties** (optional):

    ```yaml theme={null}
    # 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):

    ```yaml theme={null}
    associations: "companies,deals"  # Lädt auch Firmen- und Deal-Daten
    ```
  </Accordion>
</AccordionGroup>

### 3. Parameter-Schema definieren

```json theme={null}
{
  "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

<Tabs>
  <Tab title="Flexible Lookup">
    ```json theme={null}
    {
      "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"]}
      ]
    }
    ```
  </Tab>

  <Tab title="Mit Filteroptionen">
    ```json theme={null}
    {
      "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"]
    }
    ```
  </Tab>
</Tabs>

## Response-Verarbeitung

### Typische API-Antwort

```json theme={null}
{
  "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:

<AccordionGroup>
  <Accordion title="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."
  </Accordion>

  <Accordion title="Kontextuelle Gesprächsführung">
    **Basierend auf Lifecycle-Stage**:

    ```yaml theme={null}
    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..."
    ```
  </Accordion>

  <Accordion title="Automatische Qualifizierung">
    **Lead-Status-basierte Ansprache**:

    ```yaml theme={null}
    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."
    ```
  </Accordion>
</AccordionGroup>

## Fehlerbehandlung

### Häufige Fehlerszenarien

<Tabs>
  <Tab title="404 - Kontakt nicht gefunden">
    **Ursache**: E-Mail-Adresse existiert nicht in HubSpot

    **Graceful Fallback**:

    ```yaml theme={null}
    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
    ```
  </Tab>

  <Tab title="401 - Authentifizierungsfehler">
    **Ursache**: API-Key ungültig oder abgelaufen

    **Systemreaktion**:

    ```yaml theme={null}
    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
    ```
  </Tab>

  <Tab title="429 - Rate Limit erreicht">
    **Ursache**: Zu viele API-Anfragen in kurzer Zeit

    **Handhabung**:

    ```yaml theme={null}
    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?"
    ```
  </Tab>

  <Tab title="Timeout-Behandlung">
    **Ursache**: API-Antwort dauert länger als 5 Sekunden

    **Graceful Degradation**:

    ```yaml theme={null}
    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?"
    ```
  </Tab>
</Tabs>

## Testing und Validierung

### Automatische Tests

<Steps>
  <Step title="API-Konnektivität testen">
    Das System führt automatisch Tests mit Standard-Testwerten durch:

    * E-Mail: "[test@example.com](mailto:test@example.com)"
    * Erwartetes Verhalten: 404 oder Kontaktdaten
  </Step>

  <Step title="Performance-Monitoring">
    Überwachung kritischer Metriken:

    * Response Time: \<3 Sekunden (Ziel)
    * Success Rate: >95%
    * Error Rate: \<5%
  </Step>
</Steps>

### Manuelle Tests

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="Gesprächsfluss-Tests">
    **Realistische Szenarien testen**:

    1. **Standard-Kundenkontakt**:
       * Kunde: "Meine E-Mail ist [max@beispiel.de](mailto:max@beispiel.de)"
       * Erwartete KI-Reaktion: Personalisierte Begrüßung mit Namen und Firma

    2. **Unbekannter Kontakt**:
       * Kunde: "[test12345@nichthierregistriert.de](mailto:test12345@nichthierregistriert.de)"
       * Erwartete KI-Reaktion: Höfliche Nachfrage nach alternativer E-Mail

    3. **Performance-Test**:
       * Mehrere schnelle Abfragen hintereinander
       * Erwartetes Verhalten: Konstante Performance ohne Degradation
  </Accordion>
</AccordionGroup>

## Erweiterte Konfigurationen

### Multi-Property Lookup

```yaml theme={null}
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

<Tabs>
  <Tab title="Session-basiertes Caching">
    ```yaml theme={null}
    Caching-Strategie:
      Dauer: Bis Gesprächsende
      Zweck: Vermeidung wiederholter API-Calls im gleichen Gespräch
      Implementation: Automatisch durch Famulor-System
    ```
  </Tab>

  <Tab title="Time-based Cache">
    ```yaml theme={null}
    Für häufig abgefragte Kontakte:
      Cache-Dauer: 5 Minuten
      Aktualisierung: Bei bekannten Datenänderungen
      Fallback: Frische Datenabfrage bei Cache-Miss
    ```
  </Tab>
</Tabs>

## Integration mit anderen Tools

### Workflow-Kombination

```mermaid theme={null}
sequenceDiagram
    participant K as Kunde
    participant A as KI-Assistant
    participant H as HubSpot Tool
    participant C as Calendar Tool
    participant E as E-Mail Tool
    
    K->>A: "Meine E-Mail ist max@beispiel.de"
    A->>H: get_hubspot_contact(max@beispiel.de)
    H-->>A: Kontaktdaten + Lifecycle Stage
    
    Note over A: Lifecycle = "opportunity"
    
    A->>K: "Hallo Max! Ich sehe, wir besprechen ein Projekt."
    K->>A: "Ja, können wir einen Termin vereinbaren?"
    A->>C: check_calendar_availability()
    C-->>A: Verfügbare Termine
    A->>K: "Wie wäre Donnerstag 14:00?"
    K->>A: "Perfect!"
    A->>C: book_appointment(Thursday 14:00)
    A->>E: send_confirmation_email()
    A->>H: update_contact_notes("Termin vereinbart")
```

## Best Practices

### Performance-Optimierung

<CardGroup cols={2}>
  <Card title="Selective Properties" icon="filter">
    **Nur notwendige Daten abrufen**:

    * Standard: firstname, lastname, company
    * Bei Bedarf: jobtitle, lifecyclestage
    * Vermeiden: notes, alle custom properties
  </Card>

  <Card title="Timeout-Management" icon="clock">
    **Angemessene Timeout-Werte**:

    * Standard: 5 Sekunden
    * Critical Calls: 3 Sekunden
    * Batch Operations: 10 Sekunden
  </Card>
</CardGroup>

### Sicherheit und Compliance

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## 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

<Steps>
  <Step title="Häufige Probleme identifizieren">
    * API-Key-Ablauf (401 Errors)
    * Rate-Limiting (429 Errors)
    * Netzwerk-Timeouts
    * Falsche URL-Parameter
  </Step>

  <Step title="Monitoring einrichten">
    * Automatische Alerts bei >5% Error Rate
    * Daily Performance Reports
    * Weekly Usage Analytics
  </Step>

  <Step title="Kontinuierliche Optimierung">
    * Monatliche Performance-Reviews
    * Quarterly API-Integration-Updates
    * Customer Feedback Integration
  </Step>
</Steps>

***

<Card title="Nächste Schritte" icon="arrow-right">
  Nachdem du das HubSpot Kontakt-Abruf-Tool implementiert hast, kannst du weitere HubSpot-Integrationen hinzufügen:

  * [Deal-Management Tool](/de/automation-platform/mid-call-tools/integration-templates/hubspot-deal-management)
  * [Lead-Erstellung Tool](/de/automation-platform/mid-call-tools/integration-templates/hubspot-lead-erstellung)
  * [Webhook-Integration](/de/automation-platform/mid-call-tools/integration-templates/webhook-automation) für komplexere Workflows
</Card>

<Warning>
  **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.
</Warning>

<Tip>
  Statt einzelner HTTP-Aktionen ein ganzes Toolset auf einmal? Externen **MCP-Server** verbinden — Tools werden automatisch erkannt. Siehe [MCP-Server](/de/platform/mcp-servers).
</Tip>