Intercom API Guide: AI-Produktberater bauen statt Chatbots

Warum Standard-Bots scheitern und wie du es besser machst

Wenn du an Intercom-Bots denkst, denkst du wahrscheinlich an Fin oder einfache Entscheidungsbäume, die Nutzer fragen: 'Hast du ein Problem mit deiner Rechnung?'. Das ist großartig für den Support – es senkt die Ticketlast und hilft Kunden schnell weiter. Laut Intercom setzen bereits tausende Unternehmen auf solche Automatisierungen.

Aber wenn du ein komplexes B2B-Produkt verkaufst, reicht ein Support-Bot nicht aus. Ein potenzieller Kunde fragt nicht 'Wie setze ich mein Passwort zurück?', sondern 'Ist euer API-Plan mit meiner Enterprise-Architektur kompatibel?' oder 'Welches eurer drei Pakete passt am besten zu einem Team von 5 Entwicklern?'. Hier zeigt sich der Unterschied zwischen einem einfachen FAQ-Bot und einer echten KI-Produktberatung.

Hier scheitern Standard-Integrationen. Sie haben keinen Zugriff auf deine externe Produktdatenbank, sie verstehen den Kontext des Nutzers (z.B. 'Budget: Hoch') nicht tief genug und sie können nicht beraten. Die meisten existierenden Tutorials und auch Teile der offiziellen Intercom API Documentation konzentrieren sich auf Datensynchronisation oder einfache Support-Automatisierung – nicht auf echte Verkaufsberatung.

In diesem Artikel verlassen wir die Pfade der Standard Intercom API docs. Wir bauen keine Support-Automatisierung. Wir nutzen die Intercom API, um einen AI-Produktberater zu entwickeln. Einen Agenten, der den Kontext des Nutzers aus dem CRM liest, deine externe Produktdatenbank abfragt, eine fundierte, verkaufsorientierte Antwort generiert und bei Bedarf nahtlos an einen menschlichen Experten übergibt. Diese Herangehensweise unterscheidet sich fundamental von dem, was Consultation AI den Support-Bot traditionell leistet.

Voraussetzungen und deutsche Datenschutz-Compliance

Bevor wir eine einzige Zeile Code schreiben, müssen wir über Infrastruktur sprechen. Wenn du diesen Artikel aus Deutschland oder der EU liest, ist dieser Abschnitt der wichtigste für deine Compliance-Abteilung. Die korrekte Konfiguration der Intercom API für EU-Hosting ist keine optionale Best Practice – sie ist rechtlich erforderlich.

Authentication: Access Tokens vs. OAuth

Um mit der Intercom API zu kommunizieren, benötigst du Authentifizierung. Hier gibt es zwei grundlegende Optionen, die sich in ihren Anwendungsfällen deutlich unterscheiden:

• Access Tokens (Standard): Ideal für interne Integrationen, die nur deinen eigenen Workspace verwalten. Du findest diese im Developer Hub unter 'Authentication'. Laut Merge.dev ist dies der schnellste Weg zum Einstieg.
• OAuth: Zwingend erforderlich, wenn du eine App baust, die andere Intercom-Nutzer in ihren Workspaces installieren sollen (z.B. wenn du eine SaaS-Lösung baust, die sich in Intercom integriert). Endgrate bietet detaillierte Tutorials zu OAuth-Flows.

Für unseren internen Produktberater reicht meist ein Access Token. Wenn du jedoch planst, deine Lösung als eigenständiges Produkt anzubieten – ähnlich wie eine Shopware API Automatisierung – musst du OAuth implementieren.

Kritisch für DACH-Region: Die Base URL (EU vs. US)

Die meisten Tutorials im Web (und sogar Teile der offiziellen Intercom API documentation) gehen standardmäßig von US-Servern aus. Wenn dein Intercom-Workspace jedoch in Europa gehostet wird (was aus DSGVO-Gründen für deutsche Firmen Standard sein sollte), funktionieren Anfragen an api.intercom.io oft nicht korrekt oder leiten Daten unnötig um. Laut Intercom musst du explizit den EU-Endpoint ansprechen.

Diese Konfiguration ist essentiell, wenn du KI-gestützter Kundenservice in Deutschland anbieten möchtest. Die falsche Base URL kann nicht nur zu technischen Problemen führen, sondern auch zu GDPR-Verstößen.

Die 3 Core Endpoints für echte Beratung

Die Intercom API docs listen Dutzende Endpoints. Für einen intelligenten Berater-Bot brauchen wir jedoch primär drei spezifische Bereiche. Wir ignorieren 'Articles' oder 'Tags' vorerst und konzentrieren uns auf das Gehirn der Konversation. Diese fokussierte Herangehensweise unterscheidet einen digitaler Produktberater von einer generischen Integration.

A. Die Conversations API (Das Ohr)

Hier hören wir zu. Wenn ein Nutzer eine Frage stellt, nutzen wir diesen Endpoint, um den Text und die Metadaten zu erhalten. Achte besonders auf das Feld source.body – hier steht die eigentliche Frage des Nutzers. Laut der Intercom Conversations API Dokumentation enthält jede Konversation reichhaltige Metadaten.

Neu in 2024/2025: Intercom hat Metadaten für AI-Agenten hinzugefügt. Das Feld ai_agent_participated zeigt an, ob bereits Fin oder ein anderer Bot involviert war. Diese Information ist wichtig, um zu entscheiden, ob dein Custom-Bot eingreifen sollte oder ob die Konversation bereits von Intercoms eigenem AI-System bearbeitet wird. Die Intercom AI Agent Dokumentation erklärt diese Felder im Detail.

B. Die Contacts API & Custom Attributes (Das Gedächtnis)

Das ist der Schlüssel zur Differenzierung zwischen einem dummen Bot und einem echten Berater. Ein Berater weiß, mit wem er spricht. Über die Contacts API rufen wir nicht nur den Namen ab, sondern vor allem die Custom Attributes (Benutzerdefinierte Attribute). Die Intercom Contacts API ermöglicht dir Zugriff auf alle gespeicherten Kundeninformationen.

Stell dir vor, du hast folgende Daten über deinen Lead bereits gesammelt (z.B. beim Sign-up oder durch Enrichment-Tools):

• industry: 'Logistik'
• team_size: '50+'
• budget_tier: 'Enterprise'

Wenn der Nutzer fragt: 'Welches Produkt empfehlt ihr?', kann dein AI-Bot diese Attribute auslesen und antworten: 'Für Logistik-Unternehmen deiner Größe empfehlen wir den Enterprise-Plan, da er die nötigen API-Limits bietet.' Ohne diesen API-Call wäre die Antwort nur ein generisches 'Wir haben drei Pläne...'. Laut StackOverflow ist genau diese Kontextualisierung der häufigste Fehler bei Bot-Implementierungen.

Diese Fähigkeit macht den entscheidenden Unterschied für KI-Produktberatung Warenkorbwert – je mehr Kontext der Bot hat, desto höher die Conversion-Rate.

C. Die Admin / Reply API (Der Mund)

Um zu antworten, agieren wir als Admin. Wir können Antworten entweder als öffentliche Nachricht senden oder als Whisper (interne Notiz), falls wir erst einen menschlichen Mitarbeiter briefen wollen. Die Intercom Reply API dokumentiert alle verfügbaren Nachrichtentypen.

Die Brain-Architektur: So baust du die Logik

Lass uns die Theorie in die Praxis umsetzen. Wir bauen eine Architektur, die externe Intelligenz in den Intercom-Chat injiziert. Diese Architektur ist das Herzstück jeder erfolgreichen Consultative AI Implementation.

Der Workflow im Detail

Dieser Workflow zeigt, warum eine KI-Produktberatung ersetzt FAQ-Bots so effektiv ist: Der Bot versteht nicht nur die Frage, sondern kennt auch den Kontext des Fragenden und hat Zugriff auf Echtzeitdaten.

Code-Beispiel in Python

Dieses Beispiel zeigt das Grundgerüst eines Consultant-Bots, der die EU-Endpunkte nutzt und Kontext einbezieht. Wir nutzen hier requests für maximale Transparenz, auch wenn es SDKs gibt. Der Code basiert auf den Best Practices von Rollout.

```python import requests import json # Konfiguration für deutsche/EU Kunden REGION = 'EU' BASE_URL = 'https://api.eu.intercom.io' if REGION == 'EU' else 'https://api.intercom.io' TOKEN = 'DEIN_ACCESS_TOKEN' HEADERS = { 'Authorization': f'Bearer {TOKEN}', 'Accept': 'application/json', 'Content-Type': 'application/json', 'Intercom-Version': '2.14' # Immer aktuelle Version prüfen! } def handle_webhook(webhook_data): ''' Wird aufgerufen, wenn Intercom einen Webhook sendet. ''' conversation_id = webhook_data['data']['item']['id'] user_id = webhook_data['data']['item']['source']['author']['id'] user_message = webhook_data['data']['item']['source']['body'] # 1. Kontext laden (Wer ist der Kunde?) user_context = get_user_context(user_id) # 2. Externe Logik / AI (Hier passiert die Magie) consultant_reply = generate_ai_response(user_message, user_context) # 3. Antwort senden send_reply(conversation_id, consultant_reply) def get_user_context(intercom_user_id): ''' Holt Custom Attributes via Contacts API ''' url = f'{BASE_URL}/contacts/{intercom_user_id}' response = requests.get(url, headers=HEADERS) if response.status_code == 200: data = response.json() attributes = data.get('custom_attributes', {}) return attributes return {} def generate_ai_response(message, context): ''' Hier würdest du deine OpenAI/LLM Logik einbinden. Beispiel-Logik basierend auf Attributen. ''' industry = context.get('industry', 'Unbekannt') if 'Preis' in message and industry == 'StartUp': return 'Für Startups bieten wir spezielle Rabatte an. Sollen wir einen Call vereinbaren?' elif 'Preis' in message: return 'Unsere Enterprise-Preise richten sich nach Volumen. Hier ist die Übersicht...' return 'Ich prüfe das für dich in unserer Datenbank...' def send_reply(conversation_id, text_body): ''' Sendet die Antwort als Admin zurück in den Chat ''' url = f'{BASE_URL}/conversations/{conversation_id}/reply' payload = { 'message_type': 'comment', 'type': 'admin', 'admin_id': 'DEINE_ADMIN_ID', 'body': text_body } response = requests.post(url, headers=HEADERS, json=payload) if response.status_code != 200: print(f'Error sending reply: {response.text}') ```

Advanced Strategy: Der intelligente Human Handoff

Ein reiner AI-Bot ist riskant. Wenn der Kunde frustriert ist oder ein Kaufabschluss (High Intent) droht, muss ein Mensch übernehmen. Die meisten Bots scheitern hier und lassen den Kunden in einer Schleife hängen. Mit der Intercom API können wir den Human Handoff intelligent programmieren – ein kritischer Aspekt für erfolgreiche KI Leadgenerierung.

Wann solltest du übergeben?

Deine AI sollte den Sentiment Score (Stimmung) der Nachricht analysieren. Die Entscheidung zur Übergabe basiert auf zwei Hauptfaktoren:

• Sentiment Negative: Kunde ist wütend oder frustriert → Sofort an Support-Team eskalieren
• Intent High: Kunde fragt nach 'Vertrag', 'Angebot', 'Demo' oder konkreten Preisen → Sofort an Sales-Team eskalieren

Ein KI Produktfinder kann diese Signale automatisch erkennen und entsprechend reagieren. Die Kunst liegt darin, den richtigen Moment zu finden – zu früh übergibt unnötig an menschliche Ressourcen, zu spät verliert potenzielle Kunden.

Technische Umsetzung der Übergabe

Wir nutzen den /conversations/{id}/parts oder den spezifischen Assign-Endpoint, um die Konversation einem Team oder Admin zuzuweisen. Die Intercom Assignment API dokumentiert alle Optionen.

Der API-Call für die Zuweisung: ```json POST https://api.eu.intercom.io/conversations/{conversation_id}/parts { 'message_type': 'assignment', 'type': 'admin', 'admin_id': 'CURRENT_ADMIN_ID', 'assignee_id': 'TARGET_ADMIN_ID_OR_TEAM_ID', 'body': 'AI Handoff: Kunde zeigt hohes Kaufinteresse. Bitte übernehmen.' } ```

Ein weiterer wichtiger Aspekt: Prüfe die Office Hours deines Teams via API, bevor du eine Übergabe initiierst. Es macht keinen Sinn, eine Konversation um 3 Uhr nachts Berliner Zeit an einen menschlichen Mitarbeiter zu übergeben, wenn niemand verfügbar ist. In diesem Fall sollte der Bot stattdessen einen Termin anbieten oder eine Callback-Option setzen.

Fallstricke und Limitationen der Intercom API

Selbst erfahrene Entwickler stolpern über diese Eigenheiten der Intercom API. Die offiziellen Intercom API docs dokumentieren diese Punkte zwar, aber oft nicht prominent genug. Wenn du diese Probleme für beste Intercom Alternativen evaluierst, solltest du wissen, dass ähnliche Einschränkungen bei den meisten Anbietern existieren.

1. Rate Limiting: Die 10-Sekunden-Regel

Die Intercom API documentation gibt oft ein Limit von 1.000 Requests pro Minute an. Das klingt viel. Aber Vorsicht: Intercom verteilt dies oft auf 10-Sekunden-Fenster (ca. 166 Requests pro 10 Sekunden). Laut Intercom Help und Rollout ist dies eine häufige Fehlerquelle.

• Das Problem: Ein Burst an Traffic (z.B. ein Newsletter geht raus, 500 Leute antworten gleichzeitig) kann deinen Bot sofort blockieren (HTTP 429).
• Die Lösung: Implementiere Exponential Backoff in deinem Code. Prüfe den Header X-RateLimit-Remaining bei jeder Antwort, um zu sehen, wie viel Budget du noch hast.

Die Intercom Rate Limiting Dokumentation empfiehlt explizit, diese Header zu monitoren und entsprechend zu reagieren.

2. HTML-Formatierung: Weniger ist mehr

Du möchtest, dass dein Produktberater schöne Product Cards mit Buttons und Bildern sendet? Hier setzt die API Grenzen. Intercom unterstützt in API-Nachrichten kein volles HTML/CSS. Dies ist wichtig zu verstehen für jede digitale Produktberatung, die visuell ansprechend sein soll.

Die Intercom Message Formatting Dokumentation und die erweiterte Formatierungsdokumentation erklären diese Einschränkungen im Detail.

3. Ghost Conversations

Wenn du eine Nachricht vom Admin an den User initiierst (Outbound), erstellt Intercom manchmal eine Nachricht, die nicht sofort in der Inbox des Admins sichtbar ist, bis der Nutzer antwortet. Um dies zu umgehen und die Konversation sofort als Ticket sichtbar zu machen, gibt es Parameter wie create_conversation_without_contact_reply: true, die aber mit Vorsicht zu genießen sind. Laut Intercom API Dokumentation können sich diese Parameter in neueren API-Versionen ändern.

Praktische Anwendungsbeispiele für AI-Produktberater

Nachdem wir die technischen Grundlagen verstanden haben, schauen wir uns konkrete Anwendungsfälle an. Diese Beispiele zeigen, wie erfolgreiche Unternehmen die Intercom API für echte KI-Produktberatung nutzen.

E-Commerce: Produktempfehlungen basierend auf Kundenprofil

Ein Online-Shop für Gartengeräte nutzt Custom Attributes wie Gartengröße, Rasentyp und bisherige Käufe. Wenn ein Kunde fragt 'Welchen Rasenmäher brauche ich?', kombiniert der Bot diese Daten mit der Produktdatenbank und empfiehlt das passende Modell – inklusive Zubehör-Upselling.

B2B SaaS: Enterprise-Qualifizierung

Ein Software-Anbieter nutzt die Contacts API, um Firmendaten wie Mitarbeiterzahl, Branche und Tech-Stack abzurufen. Der Bot kann dann sofort einschätzen, ob der Lead für den Enterprise-Plan qualifiziert ist, und entsprechend die richtigen Case Studies und Pricing-Informationen präsentieren.

Finanzdienstleistungen: Compliance-konforme Beratung

Eine Versicherung nutzt den EU-Endpoint für GDPR-Compliance und speichert Beratungsgespräche als Conversation Notes. Der Bot kann Produkte empfehlen, aber bei komplexen Fragen (z.B. zu Risikolebensversicherungen) triggert er automatisch den Human Handoff an einen lizenzierten Berater.

Fazit: Baue Berater statt Anrufbeantworter

Die Intercom API ist weit mehr als ein Werkzeug zur Datensynchronisation. Sie ist die Schnittstelle, um deine proprietären Daten und moderne AI-Logik direkt in den Kundendialog zu bringen. Die Kombination aus Conversations API, Contacts API mit Custom Attributes und der Admin/Reply API ermöglicht echte Produktberatung.

Indem du den EU-Endpoint für Compliance nutzt, Custom Attributes für Kontext lädst und intelligente Handoff-Regeln definierst, verwandelst du den Intercom-Messenger von einem reinen Support-Kanal in einen automatisierten Vertriebskanal. Dies ist der Unterschied zwischen einem FAQ-Bot und einem echten AI-Produktberater.

Deine nächsten Schritte

1. Prüfe deinen aktuellen API-Token: Nutzt du OAuth oder Access Tokens? Ist der EU-Endpoint korrekt konfiguriert?
2. Teste den Abruf von Custom Attributes: Hole dir die Attribute für einen Test-User und prüfe, welche Daten bereits vorhanden sind.
3. Skizziere den Consultation Flow: Welche Daten braucht deine AI, um eine wirklich gute Antwort zu geben?
4. Implementiere Rate Limiting: Setze Exponential Backoff von Anfang an ein, bevor dein Traffic wächst.
5. Definiere Handoff-Trigger: Bei welchen Keywords oder Sentiment-Scores soll ein Mensch übernehmen?

FAQ: Häufige Fragen zur Intercom API