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 verwalteter 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, Recht oder Finanzen – 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
Um Respond by API einzurichten, 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 den Einstellungen Ihrer App.
Wählen Sie Ihre App aus oder erstellen Sie eine neue.
Gehen Sie zu API-Version und wechseln Sie zur Preview.
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 besitzt: 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 verwalteter Verfügbarkeit ist. Sie müssen zu dieser 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 sollen
Aktuelle Gesprächsnachrichten zum Kontext
Für vollständige Nutzlast- und Feldspezifikationen siehe die procedures API reference.
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 Teamkollege 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 reference.
Beste Praktiken
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 reference.
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 (Eskaltionsnachricht, Neuvergabe usw.).
Senden Sie keine doppelten Antworten: Der Callback ist nicht idempotent. Wenn Sie für denselben Schritt mehr als einmal antworten, erhalten Sie bei nachfolgenden Anfragen den Fehler 409 Conflict. Wenn Sie einen 409 erhalten, wurde Ihre ursprüngliche Antwort bereits verarbeitet.
Für Listenattribute senden Sie die Options-ID: Senden Sie nicht das Anzeigeetikett der Option, sondern deren ID aus dem Optionsarray.
Verfolgen Sie, wer antwortet: Der mit Ihrem OAuth-Token verknüpfte Teamkollege wird als Antwortender vermerkt. Erwägen Sie die Verwendung eines dedizierten Servicekontos, wenn Sie eine konsistente Identität wünschen.
Gehen Sie mit Multi-Channel-Rennen sorgfältig um: Wenn der API-Kanal zusammen mit Inbox oder Slack aktiviert ist, gewinnt die erste Antwort. Ihr System kann einen 409 erhalten, wenn ein Teamkollege zuerst über einen anderen Kanal antwortet.