Intégration API Intercom
Nous développons votre connecteur Intercom
Nous branchons Intercom à votre produit : le contact se crée à l'inscription, le chat s'ouvre avec le contexte du compte, le ticket porte le dossier métier.
- Équipe produit senior
- connecteurs de support en production
- du cadrage au monitoring
À quoi sert l'intégration Intercom et que devient la relation client une fois connectée ?
Intercom est une plateforme de relation client qui combine messagerie in-app, chat, email et support agent. L'intégrer à votre application permet d'ouvrir une conversation ou un ticket directement depuis votre produit avec le contexte du compte, d'enrichir la fiche Intercom avec les données métier de l'utilisateur, et de déclencher un message automatique quand un événement clé se produit dans votre produit. L'agent support voit l'usage réel du client sans chercher dans un autre outil, et le client reçoit un message au bon moment sans que l'équipe décide manuellement de l'envoyer.
Ce que nos clients branchent sur Intercom
Contact à l'inscription, Messenger ouvert
À l'inscription ou au changement de plan, la fiche Intercom suit. Le chat in-app parle du même humain que votre application.
Ticket d'onboarding depuis le formulaire
Le formulaire d'onboarding ouvre un ticket avec les champs métier. L'agent voit le contexte produit, pas un message orphelin.
Tracker d'incident, conversations liées
Un incident plateforme regroupe les conversations liées au même dossier. Le support suit une crise sans perdre le fil.
Portail « mes demandes »
Le client suit « mes demandes » dans votre portail. Le back-office reste hors de ce miroir.
Ce que ça change dans votre support
La technique au service d'un résultat mesurable : un contact unique, conversation et ticket distincts, un contexte produit partagé.
Chat et ticket, chacun son rôle
Le Messenger porte la conversation in-app ; le ticket porte le dossier agent. On ne mélange pas les deux : la recette reste lisible.
La région EU est cadrée dès le départ
Un workspace européen doit parler au bon point d'entrée. C'est l'argument RGPD concret pour un client français.
Le support voit le contexte sans ressaisie
Plan, compte, incident : la fiche Intercom suit le produit. L'agent arrête l'interrogatoire de première ligne.
Les notifications restent fiables
On vérifie la signature des événements Intercom. Vous agissez sur un vrai statut, pas sur un message falsifiable.
Comment nous livrons votre connecteur Intercom
Cadrage
App privée ou publique, région, conversations vs tickets, attributs custom (noms uniques). On liste les cas limites avant d'écrire une ligne de code.
Développement
Vérif SHA-1 sur le corps brut, 200 immédiat, dédup notif_..., contact.id stocké chez vous. File dimensionnée pour les pics contact / content_stat.
Recette
Conversation vs ticket, delete irréversible, 400 INVALID_PARAMETER sur attributs homonymes, 2 500 liens tracker. On rejoue un 429 webhook envoyé par vous.
Monitoring
Latence handler, 1 000 erreurs / 15 min, throttle 429 (1 min → 2 h puis drop). Vous savez qu'un flux est cassé avant vos clients.
Ce que permet l'API Intercom
- Contacts
- Users et leads. Upsert depuis le produit, identifiant Intercom stocké chez vous. Custom attributes : noms uniques, sinon PUT conversations renvoie 400 INVALID_PARAMETER.
- Conversations Messenger
- GET/POST /conversations, retrieve (plafond 500 parts les plus récentes), reply, tags. Pagination défaut 20. Ce n'est pas un ticket agent.
- Tickets Inbox
- POST /tickets, POST /tickets/enqueue (async), search, reply, tags, change_type, link/unlink. Delete irréversible, données sensibles effacées.
- Webhooks Developer Hub
- Souscription uniquement dans le Hub, associés à l'app, tous les workspaces où elle est installée. URL HTTPS, validation HEAD. Topics versionnés (ticket.created).
Le vocabulaire de l'API Intercom
- Conversation vs Ticket
- Conversation : Messenger, temps réel produit, 500 parts. Ticket : Inbox structurée, types, attributs. POST /conversations n'ouvre pas un ticket agent.
- X-Hub-Signature
- sha1= + HMAC-SHA1 hex du JSON, client_secret de l'app (RFC 2104). User-Agent intercom-parrot-service-client/1.0. Ce n'est pas SHA-256.
- api.eu.intercom.io
- Host EU. US : api.intercom.io. AU : api.au.intercom.io. Un workspace EU appelé sur le host US est un bug, pas une optimisation.
- Fenêtre REST 10 secondes
- 10 000 / min / app ⇒ max 1 666 / 10 s. 25 000 / min / workspace. Apps privées : les apps du workspace partagent le seau workspace. Headers X-RateLimit-Limit, -Remaining, -Reset.
- Priorité webhook < 500 ms
- Réponse < 500 ms : file haute. Sinon file basse. Duplicate si pas de 200 en 5 000 ms. Pause 15 min après 1 000 erreurs HTTP consécutives / 15 min. Private apps : suspension après 7 jours d'erreurs.
- linked_conversation_limit_exceeded
- Un ticket tracker ne peut pas lier plus de 2 500 conversations. Utile pour un incident plateforme, à cadrer avant de tout rattacher.
Les contraintes réelles de l'API Intercom
Les webhooks se souscrivent dans le Hub
Plus d'API de souscription. Associés à l'app, notifications de tous les workspaces où elle est installée. Les tutos anciens qui POST une subscription sont faux.
Répondre vite, ou perdre des events
200 en moins de 5 s, idéalement < 500 ms. Un 429 de votre côté throttle 1 min puis 2 h, puis drop. En EU, Intercom peut émettre 20 000 events / min : votre endpoint est souvent plus petit.
Delete est destructif
Delete ticket : irréversible, données sensibles effacées. Delete conversation : retain_metrics true/false, scope dédié si false. Journal d'audit avant, décision produit explicite.
App publique : pas de token collé
Demander un Access Token à un client est contraire aux ToS et peut faire révoquer l'accès. App privée : token du workspace. OAuth pour le multi-workspace.
API Intercom ou API Freshdesk ?
Deux modèles de support. Intercom vit dans le produit (Messenger + Inbox) ; Freshdesk est un helpdesk tickets classique.
| Critère | IntercomCette page | FreshdeskHelpdesk tickets |
|---|---|---|
| Objet | Conversations + Tickets | Tickets helpdesk |
| Canal | Messenger in-app | Email / portail / phone |
| Webhooks | Hub only, SHA-1 X-Hub-Signature | Automations, pas de bus dédié v2 |
| Région | api.eu.intercom.io | {domaine}.freshdesk.com |
| Quota REST | 10 000 / min / app | Selon le plan, headers |
| Delete | Irréversible, retain_metrics | Soft + hard_delete |
| Le bon cas | Produit avec chat + inbox | File tickets classique |
Les trois (Intercom, Freshdesk, Zendesk) ne sont pas le même connecteur. Intercom sépare conversation et ticket et signe en SHA-1. Freshdesk facture les include. Zendesk impose l'export incrémental. C'est un arbitrage de cadrage.
Ce que nous mesurons sur une intégration Intercom
Les autres API de support
Si Intercom n'est pas le bon socle, ces options se discutent au cadrage.
IntercomNous développons votre connecteur IntercomCette page
FreshdeskTickets v2, contacts, include facturé, automations plutôt qu'un bus d'events.
ZendeskTickets vs Requests, Incremental Export, safe_update, webhooks HMAC SHA-256.On combine Intercom avec
La stack qui entoure Intercom sur nos projets.
Intégration Intercom : vos questions
Trois étapes. D'abord figer le host régional et le mode d'auth : Access Token de workspace pour une app privée, OAuth pour une app publique (jamais un token demandé au client). Ensuite le modèle : contact.id chez vous, conversations Messenger distinctes des tickets Inbox, attributs custom aux noms uniques. Enfin les webhooks dans le Developer Hub : vérifier X-Hub-Signature SHA-1 sur le corps brut, répondre 200 tout de suite, dédupliquer sur l'id de notification, se fier à created_at faute d'ordre garanti. La partie sensible n'est pas le POST contact, c'est le handler webhook et le plafond 2 500 liens tracker.
Oui dès que le workspace est en région EU. Un workspace EU appelé sur api.intercom.io est un bug de configuration, pas un détail. Pour un client français qui refuse le routing US, le host EU est un argument RGPD concret, posé au cadrage, pas après la première 4xx. AU : api.au.intercom.io. On ne bascule pas de région à chaud sans le savoir. Le token et le host sont une paire : les mélanger produit des 4xx opaques.
Une conversation est le fil Messenger (in-app), avec un plafond de 500 parts à la lecture. Un ticket est l'objet Inbox : types, attributs, file d'agents. POST /conversations crée un message initié par un contact, pas un ticket. POST /tickets (ou /tickets/enqueue) crée l'objet agent. Un tracker peut lier jusqu'à 2 500 conversations. Delete sur l'un ou l'autre est destructif. Les mélanger est l'erreur de recette la plus fréquente.
Un premier flux utile, typiquement l'upsert contact et une conversation Messenger, se livre en deux à trois semaines. Une chaîne tickets, search portail, tracker d'incident et webhooks Hub demande plutôt six à huit semaines : la région, le HMAC SHA-1 et le dimensionnement du handler pèsent autant que le CRUD. Nous cadrons le périmètre en amont et vous donnons une estimation ferme avant de commencer.
Intercom si le support vit dans le produit (Messenger + Inbox) et que la région EU compte. Freshdesk si vous voulez un helpdesk tickets classique, contacts, automations. Zendesk si le support entreprise est le système d'enregistrement, avec export incrémental et safe_update. SHA-1 chez Intercom, SHA-256 chez Zendesk, pas de bus dédié chez Freshdesk : ce n'est pas le même connecteur. Le Hub à la place d'une API de souscription est le piège des tutos anciens.
Un projet d'intégration Intercom ?
Parlons-en. 30 minutes pour cadrer contacts, tickets et région, et vous dire franchement ce qui est faisable.
Parler de mon projet Intercom