Der Respond by API-Kanal ermöglicht es Ihnen, Human-in-the-Loop (HITL)-Schritte in Fin Procedures mit Ihren eigenen Systemen über webhooks und die Intercom API zu verbinden. Wenn Fin einen HITL-Schritt erreicht, sendet Intercom einen webhook an Ihren Endpunkt. Ihr System verarbeitet die Anfrage, füllt die erforderlichen Attribute aus und sendet eine Antwort zurück, sodass das Verfahren automatisch fortgesetzt werden kann.
Hinweis: Diese Funktion befindet sich derzeit in der verwalteten Verfügbarkeit. Um sie zu nutzen, muss Ihre Developer Hub-App auf die Preview API-Version eingestellt sein.
Beispiele
Hier sind einige Möglichkeiten, wie Sie diese Funktion nutzen können:
Automatisierte Genehmigungsworkflows: Leiten Sie Rückerstattungs- oder Rabattgenehmigungen an ein internes Tool weiter, das Geschäftsregeln anwendet und automatisch antwortet
Benutzerdefinierte Team-Dashboards: Zeigen Sie HITL-Anfragen in Ihren eigenen Support-Tools oder im internen Portal neben anderen Aufgaben an
Eskalation an externe Teams: Leiten Sie Fragen an Teams weiter, die Intercom nicht verwenden – wie Engineering, Legal oder Finance – und erfassen Sie deren Antwort
Audit- und Compliance-Protokollierung: Protokollieren Sie jede HITL-Entscheidung in einem Compliance-System, bevor Sie antworten, und erstellen Sie so eine automatische Dokumentation
Bevor Sie beginnen
Für die Einrichtung von Respond by API benötigen Sie:
Eine Fin Procedure mit mindestens einem Human-in-the-Loop-Schritt
Eine Developer Hub-App – erstellen Sie eine unter Einstellungen > Developer Hub, falls Sie noch keine haben
Einen HTTPS-Endpunkt, der webhook-Anfragen empfangen kann
Ihre Developer Hub-App muss die OAuth-Berechtigungen read_conversations und write_conversations besitzen
Schritt 1: Aktivieren Sie Ask via webhook in Ihrem Verfahren
Öffnen Sie das Verfahren, das Sie im Verfahren-Editor konfigurieren möchten.
Wählen Sie Ihren Human-in-the-Loop-Schritt aus.
Öffnen Sie das Einstellungsfenster des Schritts, indem Sie auf das Zahnrad-Symbol klicken.
Wählen Sie den Tab Weitere Kanäle.
Erweitern Sie den Abschnitt Ask via webhook.
Schalten Sie Für dieses Verfahren aktivieren ein.
Klicken Sie auf Webhook-Einrichtung überprüfen, um zu bestätigen, dass Ihre Developer Hub-App korrekt abonniert ist.
Speichern Sie Ihr Verfahren.
Nach dem Klicken auf Webhook-Einrichtung überprüfen sehen Sie eine der folgenden Meldungen:
„Webhook verbunden.“ – Ihr webhook ist korrekt eingerichtet
„Kein webhook gefunden.“ – Sie müssen Ihren webhook im Developer Hub konfigurieren (siehe Schritt 2)
Wenn die Überprüfung fehlschlägt, klicken Sie auf Developer Hub, um die Konfiguration Ihrer App in einem neuen Tab zu öffnen.
Hinweis: Der Ask via webhook-Kanal funktioniert zusammen mit den Inbox- und Slack-Kanälen. Wenn ein HITL-Schritt erreicht wird, werden alle aktivierten Kanäle gleichzeitig benachrichtigt. Der Kanal, der zuerst antwortet, gewinnt – nachfolgende Antworten werden abgelehnt.
Schritt 2: Konfigurieren Sie Ihren webhook im Developer Hub
Gehen Sie zu Einstellungen > Developer Hub oder navigieren Sie direkt zu Ihren App-Einstellungen.
Wählen Sie Ihre App aus oder erstellen Sie eine neue.
Wechseln Sie zu API-Version und stellen Sie auf Preview um.
Gehen Sie zu Webhooks in der Konfiguration Ihrer App.
Geben Sie die URL Ihres webhook-Endpunkts ein (muss HTTPS sein).
Fügen Sie das Thema procedure.hitl_notification.created zu Ihren abonnierten Themen hinzu.
Stellen Sie sicher, dass Ihre App die erforderlichen OAuth-Berechtigungen hat: read_conversations (erforderlich zum Empfangen von webhook-Benachrichtigungen) und write_conversations (erforderlich zum Senden von Callback-Antworten über die API).
Speichern Sie Ihre webhook-Konfiguration.
Wichtig: Das HITL-webhook-Thema ist nur in der Preview API-Version verfügbar, solange diese Funktion in der verwalteten Verfügbarkeit ist. Sie müssen auf diese Version wechseln, bevor das Thema in der Liste der webhook-Themen erscheint.
Schritt 3: Verarbeiten Sie die webhook-Nutzlast
Wenn ein Verfahren einen Human-in-the-Loop-Schritt mit aktiviertem Ask via webhook erreicht, sendet Intercom eine POST-Anfrage an Ihren webhook-Endpunkt. Die Nutzlast enthält:
Die Gesprächs-ID
Die Frage, die Fin stellt
Die Attribute, die Ihr System ausfüllen muss
Eine Callback-URL, an die Sie Ihre Antwort senden
Aktuelle Gesprächsnachrichten als Kontext
Für vollständige Nutzlast- und Feldspezifikationen siehe die Procedures API-Referenz.
Schritt 4: Senden Sie eine Callback-Antwort
Sobald Ihr System die HITL-Anfrage verarbeitet hat, senden Sie eine POST-Anfrage an die in der webhook-Nutzlast angegebene callback_url. Fügen Sie die step_id und die Werte für jedes Attribut aus attributes_to_collect hinzu. Authentifizieren Sie sich mit einem Bearer-Token, das die OAuth-Berechtigung write_conversations besitzt.
Nach einer erfolgreichen Antwort setzt Fin das Verfahren mit den von Ihnen bereitgestellten Attributwerten fort. Der mit Ihrem OAuth-Token verknüpfte Mitarbeiter wird als derjenige vermerkt, der geantwortet hat.
Für das vollständige Format der Callback-Anfrage, Authentifizierungsdetails, unterstützte Datentypen und Fehlercodes siehe die Procedures API-Referenz.
Best Practices
Beachten Sie diese Punkte beim Erstellen Ihrer Integration:
Überprüfen Sie webhook-Signaturen: Intercom signiert webhook-Nutzlasten mit HMAC. Überprüfen Sie immer die Signatur, um die Echtheit der Anfrage zu bestätigen. Details finden Sie in der Procedures API-Referenz.
Antworten Sie vor Ablauf der Zeit: HITL-Anfragen haben eine konfigurierbare Wartezeit, die im Verfahren-Editor festgelegt wird. Wenn vor expires_at keine Antwort eingeht, führt das Verfahren das konfigurierte Timeout-Verhalten aus (Eskalationsnachricht, Neuvergabe usw.).
Senden Sie keine doppelten Antworten: Der Callback ist nicht idempotent. Wenn Sie für denselben Schritt mehr als einmal antworten, erhalten Sie 409 Conflict. Bei einem 409 wurde Ihre ursprüngliche Antwort bereits verarbeitet.
Senden Sie bei Listenattributen die Options-ID: Senden Sie nicht das Anzeigelabel der Option, sondern deren ID aus dem Options-Array.
Verfolgen Sie, wer antwortet: Der mit Ihrem OAuth-Token verknüpfte Mitarbeiter wird als Antwortender vermerkt. Erwägen Sie die Verwendung eines dedizierten Servicekontos für eine konsistente Identität.
Gehen Sie mit Multi-Channel-Rennen vorsichtig um: Wenn der API-Kanal zusammen mit Inbox oder Slack aktiviert ist, gewinnt die erste Antwort. Ihr System kann einen 409 erhalten, wenn ein Mitarbeiter zuerst über einen anderen Kanal antwortet.