Le canal Respond by API vous permet de connecter les étapes Human-in-the-Loop (HITL) dans Fin Procedures à vos propres systèmes en utilisant les webhooks et l'API Intercom. Lorsque Fin atteint une étape HITL, Intercom envoie un webhook à votre point de terminaison. Votre système traite la demande, remplit les attributs requis et envoie une réponse, permettant à la procédure de continuer automatiquement.
Note : Cette fonctionnalité est actuellement en disponibilité gérée. Pour l'utiliser, votre application Developer Hub doit être configurée sur la version Preview de l'API.
Exemples
Voici quelques façons d'utiliser cette fonctionnalité :
Workflows d'approbation automatisés : Acheminer les approbations de remboursement ou de réduction vers un outil interne qui applique les règles métier et répond automatiquement
Tableaux de bord personnalisés pour les coéquipiers : Affichez les demandes HITL dans vos propres outils de support ou portail interne aux côtés d'autres tâches
Escalade vers des équipes externes : Transférez les questions aux équipes qui n'utilisent pas Intercom — comme l'ingénierie, le juridique ou la finance — et capturez leur réponse
Journalisation d'audit et de conformité : Enregistrez chaque décision HITL dans un système de conformité avant de répondre, créant une trace papier automatique
Avant de commencer
Pour configurer Respond by API, vous aurez besoin de :
Une Fin Procedure avec au moins une étape Human-in-the-Loop
Une application Developer Hub — créez-en une dans Paramètres > Developer Hub si vous n'en avez pas encore
Un point de terminaison HTTPS capable de recevoir des requêtes webhook
Votre application Developer Hub doit avoir les scopes OAuth read_conversations et write_conversations
Étape 1 : Activez Ask via webhook dans votre procédure
Ouvrez la procédure que vous souhaitez configurer dans l'éditeur de procédures.
Sélectionnez votre étape Human-in-the-Loop.
Ouvrez le panneau Paramètres de l'étape en cliquant sur l'icône d'engrenage.
Sélectionnez l'onglet Plus de canaux.
Développez la section Ask via webhook.
Activez Activer pour cette procédure.
Cliquez sur Vérifier la configuration du webhook pour confirmer que votre application Developer Hub est correctement abonnée.
Enregistrez votre procédure.
Après avoir cliqué sur Vérifier la configuration du webhook, vous verrez l'un des messages suivants :
"Webhook connecté." — votre webhook est correctement configuré
"Aucun webhook trouvé." — vous devez configurer votre webhook dans Developer Hub (voir Étape 2)
Si la vérification échoue, cliquez sur Developer Hub pour ouvrir la configuration de votre application dans un nouvel onglet.
Note : Le canal Ask via webhook fonctionne en parallèle avec les canaux Inbox et Slack. Lorsqu'une étape HITL est atteinte, tous les canaux activés sont notifiés en même temps. Le premier canal à répondre l'emporte — les réponses suivantes sont rejetées.
Étape 2 : Configurez votre webhook dans Developer Hub
Allez dans Paramètres > Developer Hub, ou accédez directement aux paramètres de votre application.
Sélectionnez votre application, ou créez-en une nouvelle.
Allez dans Version API et passez en Preview.
Allez dans Webhooks dans la configuration de votre application.
Entrez l'URL de votre point de terminaison webhook (doit être HTTPS).
Ajoutez le sujet procedure.hitl_notification.created à vos sujets abonnés.
Assurez-vous que votre application dispose des scopes OAuth requis : read_conversations (nécessaire pour recevoir les notifications webhook) et write_conversations (nécessaire pour envoyer des réponses de rappel via l'API).
Enregistrez la configuration de votre webhook.
Important : Le sujet webhook HITL n'est disponible que sur la version Preview de l'API tant que cette fonctionnalité est en disponibilité gérée. Vous devez passer à cette version avant que le sujet n'apparaisse dans la liste des sujets webhook.
Étape 3 : Traitez la charge utile du webhook
Lorsqu'une procédure atteint une étape Human-in-the-Loop avec Ask via webhook activé, Intercom envoie une requête POST à votre point de terminaison webhook. La charge utile inclut :
L'ID de la conversation
La question posée par Fin
Les attributs que votre système doit remplir
Une URL de rappel pour envoyer votre réponse
Les messages récents de la conversation pour le contexte
Pour la charge utile complète et les spécifications des champs, consultez la référence API des procédures.
Étape 4 : Envoyez une réponse de rappel
Une fois que votre système a traité la demande HITL, envoyez une requête POST à callback_url fournie dans la charge utile du webhook. Incluez step_id et les valeurs pour chaque attribut listé dans attributes_to_collect. Authentifiez-vous avec un jeton Bearer disposant du scope OAuth write_conversations.
Après une réponse réussie, Fin reprend la procédure en utilisant les valeurs d'attribut que vous avez fournies. Le coéquipier associé à votre jeton OAuth est enregistré comme celui qui a répondu.
Pour le format complet de la requête de rappel, les détails d'authentification, les types de données pris en charge et les codes d'erreur, consultez la référence API des procédures.
Bonnes pratiques
Gardez ces points à l'esprit lors de la création de votre intégration :
Vérifiez les signatures webhook : Intercom signe les charges utiles webhook avec HMAC. Vérifiez toujours la signature pour confirmer que la requête est authentique. Consultez la référence API des procédures pour plus de détails.
Répondez avant le délai d'attente : Les demandes HITL ont un temps d'attente configurable défini dans l'éditeur de procédures. Si aucune réponse n'est reçue avant expires_at, la procédure exécute son comportement de délai d'attente configuré (message d'escalade, réaffectation, etc.).
Ne soumettez pas de réponses en double : Le rappel n'est pas idempotent. Si vous soumettez une réponse plus d'une fois pour la même étape, les requêtes suivantes renvoient 409 Conflict. Si vous recevez un 409, votre réponse originale a déjà été traitée.
Pour les attributs de liste, envoyez l'id de l'option : N'envoyez pas le libellé affiché de l'option — envoyez son id depuis le tableau des options.
Suivez qui répond : Le coéquipier associé à votre jeton OAuth est enregistré comme le répondant. Envisagez d'utiliser un compte de service dédié si vous souhaitez une identité cohérente.
Gérez gracieusement les courses multi-canaux : Si le canal API est activé avec Inbox ou Slack, la première réponse l'emporte. Votre système peut recevoir un 409 si un coéquipier répond d'abord via un autre canal.