Utilisez cet article pour configurer votre environnement développeur Intercom, configurer un domaine Help Center personnalisé avec SSL, authentifier votre application via des jetons d'accès ou OAuth, et gérer les contacts, conversations et tickets via l'API Intercom (Application Programming Interface). Il couvre également les webhooks, la pagination, la création d'applications Messenger et Inbox, ainsi que le dépannage des erreurs courantes d'API et SSL. Destiné aux développeurs créant des intégrations avec Intercom.

Vous pouvez créer un nouvel espace de travail développeur pour développer des applications. Les espaces de travail développeur sont gratuits et destinés uniquement au développement. Une fois l'espace créé, vous pouvez suivre ce guide pour créer une application et effectuer votre premier appel API.

Vous pouvez créer une nouvelle application pour votre espace de travail de production et obtenir le jeton d'accès pour l'application en vous rendant sur https://app.intercom.com/a/apps/{your-workspace-id}/developer-hub/

Lorsque vous activez votre Articles Help Center, votre contenu est disponible par défaut via intercom.help. Votre URL ressemblera à ceci : intercom.help/exampleapp.

Si vous souhaitez utiliser une URL différente, vous pouvez en créer une en configurant manuellement un domaine personnalisé. Cela implique d'entrer le domaine personnalisé dans les paramètres de votre Help Center, de créer un enregistrement CNAME personnalisé, et éventuellement de configurer SSL. Retrouvez les instructions complètes dans notre documentation développeur. Si votre Help Center affiche une erreur « introuvable » après la configuration d'un domaine personnalisé, vérifiez votre enregistrement CNAME pour vous assurer que votre sous-domaine pointe vers l'hôte Intercom correct : • Pour la configuration HTTPS rapide : us.intercomhelpcenter.com (région US) • Pour la configuration manuelle/HTTP : custom.intercom.help (région US) Vérifiez également que le protocole de sécurité sélectionné dans les paramètres de votre Help Center correspond à votre configuration DNS.

SSL (ou TLS) est la méthode la plus utilisée pour sécuriser la connexion entre votre serveur et votre navigateur. Il garantit que la connexion entre le serveur et le navigateur est chiffrée et sécurisée, et apparaît sous la forme HTTPS.

Il existe deux façons de configurer SSL avec Articles sur votre domaine personnalisé :

Oui ! Si vous activez « HTTPS (quick setup) » dans les paramètres de votre Help Center, Intercom provisionnera et gérera automatiquement un certificat SSL pour votre domaine personnalisé (comme https://help.ourdomain.com). Il n'est pas nécessaire de configurer manuellement SSL — il suffit de pointer votre CNAME vers us.intercomhelpcenter.com, et nous nous occupons du reste.

Si vous souhaitez passer votre domaine personnalisé en HTTPS :

Vous pouvez configurer SSL pour votre domaine personnalisé afin de garder les informations sensibles chiffrées. Si vous souhaitez le faire, assurez-vous d'avoir configuré votre CNAME avec un fournisseur DNS qui supporte SSL, comme Cloudflare.

Suivez le guide dans notre documentation développeur pour configurer SSL. Notez que selon le fournisseur choisi, les étapes de configuration peuvent varier.

Si les étapes standard de configuration SSL et HTTPS n'ont pas résolu votre problème, les scénarios suivants couvrent les cas particuliers courants pour les domaines personnalisés du Help Center :

1. Domaine non sécurisé

Erreur ERR_SSL_VERSION_OR_CIPHER_MISMATCH

2. Configuration HTTPS bloquée en attente

3. Option HTTPS (Configuration rapide) non disponible

4. Erreur d'accès refusé

Si l'URL d'un article migré ne fonctionne plus après le transfert de contenu vers Intercom :

Si votre Help Center affiche une erreur « Non trouvé » sur l'URL publique mais que les articles apparaissent correctement dans votre espace de travail :

La version actuelle de l'API est 2.15. Vous pouvez trouver la documentation de l'API sur notre site de documentation pour développeurs. Vous pouvez aussi changer la version utilisée par votre application dans votre Developer Hub en suivant les étapes indiquées dans ce guide.

Si vous utilisez l'API Intercom, vous pouvez aussi changer la version dans l'en-tête HTTP de votre requête.

Les endpoints suivants sont disponibles dans la version 2.15 de l'API Intercom :

Oui, si vous souhaitez déclencher un article dans le Messenger, vous pouvez utiliser la méthode showArticle de l'API JavaScript. L'article s'ouvrira dans le Messenger et cliquer sur le bouton retour du Messenger reviendra au contexte précédent. Si le Messenger est fermé lorsque la méthode est appelée, il s'ouvrira d'abord puis l'article sera affiché. Ceci est disponible sur toutes les plateformes dans le Messenger.

Dans Intercom, les users sont classés sous l'étiquette de contacts. Il n'existe pas de point de terminaison pour créer des contacts en masse via l'API, mais vous pouvez utiliser le point de terminaison create contacts pour créer un script qui importe des users ou suivre ce tutoriel qui vous fournira des exemples de code pour commencer.

Assurez-vous de configurer un contrôle de limitation de débit pour vous assurer de ne pas dépasser la limite, qui est actuellement de 10 000 appels API par minute pour chaque application et de 25 000 appels API par minute par espace de travail.

L'API Intercom n'offre pas de point de terminaison dédié à la création en masse de contacts. Pour importer des contacts à grande échelle, utilisez le point de terminaison create contact en boucle avec une gestion appropriée des limites de débit. Assurez-vous que votre script respecte les limites de débit (10 000 appels API par minute par application ; 25 000 par minute par espace de travail).

Les opérations en masse suivantes ne sont pas disponibles via l'API et doivent être gérées par des requêtes uniques en boucle ou par exportation/importation manuelle :

Pour récupérer les données d'un contact archivé, vous devez d'abord désarchiver le contact, ce que vous pouvez faire avec le point de terminaison unarchive contact API si vous avez l'ID du contact.

Ensuite, vous pourrez accéder à nouveau aux données des contacts via le point de terminaison get a contact API et à leurs conversations via le point de terminaison retrieve a conversation API.

Non, il n'existe actuellement aucun moyen de supprimer des notes individuelles ou de supprimer en masse des notes des contacts via l'API. Si cette fonctionnalité est importante pour vos opérations, veuillez visiter le Product Wishlist pour créer, commenter ou voter pour une demande de fonctionnalité. Les notes peuvent être supprimées manuellement dans l'espace de travail, mais une seule à la fois.

Si vous souhaitez assigner une conversation à une équipe via l'API, vous avez deux options.

La première option est d'assigner une conversation directement à un administrateur ou à une équipe en utilisant le point de terminaison manage a conversation API. Vous devez avoir accès à l'ID provisionné Intercom de la conversation ainsi qu'à admin_id et assignee_id.

L'autre option est d'exécuter des règles d'assignation que vous avez déjà configurées sur la conversation en utilisant le point de terminaison run assignment rules on a conversation API. Vous devez avoir accès à l'ID provisionné Intercom de la conversation.

Vous pouvez tester cette fonctionnalité depuis la fonctionnalité "Try It" dans notre documentation développeur, la collection Intercom Postman, ou dans votre propre terminal ou IDE (environnement de développement intégré). N'oubliez pas d'utiliser votre jeton d'accès Intercom comme jeton bearer.

Une note est un commentaire interne visible uniquement par les coéquipiers. Pour ajouter une note à une conversation, vous pouvez utiliser le point de terminaison reply to a conversation API. Vous devrez choisir un messsage_type de note et un type "admin" ainsi que l'admin_id d'où doit provenir la note.

Vous pouvez tester cette fonctionnalité depuis la fonctionnalité "Try It" dans notre documentation développeur, la collection Intercom Postman, ou dans votre propre terminal ou IDE. N'oubliez pas d'utiliser votre jeton d'accès Intercom comme jeton bearer.

Si vous avez déjà créé un tag dans l'interface utilisateur, vous pouvez utiliser ce tag pour l'appliquer aux conversations. Vous pouvez aussi créer un nouveau tag en utilisant l'API.

Pour utiliser le point de terminaison add tag to a conversation API, vous devrez avoir accès au conversation_id de la conversation à taguer, à l'ID provisionné Intercom du tag et à l'admin_id.

Vous pouvez tester cette fonctionnalité depuis la fonctionnalité "Try It" dans notre documentation développeur, la collection Intercom Postman, ou dans votre propre terminal ou IDE. N'oubliez pas d'utiliser votre jeton d'accès Intercom comme jeton bearer.

Vous pouvez créer une conversation depuis l'API initiée par un contact (c'est-à-dire un user ou un lead) en utilisant le point de terminaison create a conversation API. La conversation peut être uniquement un message in-app.

Vous aurez également besoin de l'ID provisionné Intercom du contact et du texte du corps à utiliser comme corps du message lors de la requête.

Vous pouvez tester cette fonctionnalité depuis la fonctionnalité "Try It" dans notre documentation développeur, la collection Intercom Postman, ou dans votre propre terminal ou IDE. N'oubliez pas d'utiliser votre jeton d'accès Intercom comme jeton bearer.

Pour fermer une conversation via l'API, vous pouvez utiliser le point de terminaison manage a conversation API. Vous devrez avoir l'ID provisionné Intercom de la conversation, votre admin_id et utiliser un message_type "close".

Si vous devez uniquement expurger une certaine partie de la conversation, utilisez le point de terminaison redact a conversation part API.

Vous pouvez tester cette fonctionnalité depuis la fonctionnalité "Try It" dans notre documentation développeur, la collection Intercom Postman, ou dans votre propre terminal ou IDE. N'oubliez pas d'utiliser votre jeton d'accès Intercom comme jeton bearer.

Pour configurer une notification personnalisée lorsqu'une action est effectuée, comme l'assignation d'un coéquipier à une conversation, vous pouvez utiliser les webhooks.

Vous devrez utiliser le sujet de conversation conversation.admin.assigned. Vous pouvez trouver tous les sujets de conversation dans notre documentation développeur.

Vous pouvez ensuite vous abonner à ce sujet webhook dans le hub développeur en suivant les étapes de ce guide. Vous devrez également disposer d'une URL de point de terminaison accessible publiquement pour que l'action soit effectuée une fois que le webhook est déclenché afin de livrer la notification à votre canal de choix.

Les conversations secondaires n'ont pas de point de terminaison dédié, vous ne pouvez donc pas les récupérer directement. Cependant, lorsque vous récupérez une conversation à laquelle la conversation secondaire est attachée, vous verrez des parties de conversation qui apparaissent comme "part_type": "side_conversation_reply" avec le contenu des messages de l'user dans la conversation secondaire.

Pour créer un ticket en utilisant l'API Intercom, vous devez d'abord créer ou obtenir le type de ticket pour étiqueter le nouveau ticket. Ensuite, vous pouvez créer le ticket en utilisant une requête curl ou avec un langage de programmation de votre choix.

Suivez ce guide dans notre documentation développeur pour créer un type de ticket et créer un nouveau ticket.

Si vous utilisez l'API pour récupérer des tickets et des données de ticket, vous pouvez utiliser le point de terminaison search tickets API. Pour exclure les types de tickets back office, définissez le champ sur ticket_type_id et utilisez l'opérateur != pour exclure le ticket_type_id attribué aux types de tickets back office.

Si vous utilisez l'API pour récupérer une conversation ou lister des conversations avec des tickets back office associés aux conversations et que vous souhaitez les exclure, vous pouvez également filtrer tous les résultats ayant le type de ticket back office comme attribut. Les tickets liés peuvent être trouvés dans le paramètre tickets de la réponse ou sous linked_objects.

Une autre option disponible est d'utiliser l'API pour taguer les conversations avec un ticket back office associé. Vous pouvez ensuite utiliser le tag pour filtrer par catégorie de ticket.

Si vous recevez un message 403 API Plan restricted dans une réponse, cela signifie que l'API que vous essayez d'utiliser n'est pas disponible dans le plan de votre application.

Pour accéder à l'API, vous devez mettre à niveau votre plan. Vous pouvez en savoir plus sur les plans Intercom sur cette page. Vous trouverez une liste complète des codes d'erreur et des réponses HTTP dans notre documentation développeur.

Si vous recevez un message 409 conflict dans une réponse, cela signifie qu'il existe des données dans votre espace de travail Intercom qui entrent en conflit avec les données de la requête. Cela peut se produire si vous essayez de créer un contact et qu'un contact avec cette adresse e-mail est déjà ajouté dans votre application.

Pour éviter cette erreur, vous pouvez utiliser le point de terminaison de mise à jour ou créer un nouveau contact par user_id. Vous trouverez une liste complète des codes d'erreur et des réponses HTTP dans notre documentation développeur.

Si vous recevez un message 429, cela signifie que le client a atteint ou dépassé une limite de taux, ou que le serveur est surchargé. Chaque application a une limite de taux par défaut de 10 000 appels API par minute pour chaque application et 25 000 appels API par minute par espace de travail. Plus d'informations sur les limites de taux sont disponibles dans notre documentation développeur.

Pour éviter cette erreur, vous pouvez configurer un contrôle de limitation de taux pour vous assurer de ne pas atteindre la limite. Vous trouverez une liste complète des codes d'erreur et des réponses HTTP dans notre documentation développeur.

Les applications privées ont une limite de taux par défaut de 10 000 appels API par minute par application et 25 000 appels API par minute par espace de travail. Cela signifie que si un espace de travail a plusieurs applications privées installées, chacune contribue au nombre total de requêtes.

Les applications publiques ont une limite de taux par défaut de 10 000 appels API par minute pour chaque application et 25 000 appels API par minute par espace de travail. Cela signifie que si un espace de travail a plusieurs applications publiques installées, chacune a sa propre limite de requêtes sans contribuer aux autres. Plus d'informations sur les limites de taux sont disponibles dans notre documentation développeur.

Si vous créez vos propres rapports en utilisant l'API, vous pouvez remarquer des différences entre les deux rapports. Cela peut arriver pour plusieurs raisons.

Un problème courant est lorsque les dates et heures ne correspondent pas. Cela est souvent dû au fait que le fuseau horaire utilisé dans votre espace de travail Intercom est différent de celui utilisé pour interroger l'API. Pour corriger cela, ajustez les paramètres de votre requête API pour correspondre au fuseau horaire de votre espace de travail, ou modifiez le fuseau horaire de votre rapport personnalisé.

Un autre problème est que vous pouvez utiliser des métriques qui ne correspondent pas aux métriques de l'interface de reporting Intercom. Certaines métriques disponibles dans l'interface de reporting ne sont pas disponibles via l'API car ce sont des métriques calculées. Certaines peuvent être créées en utilisant l'API et en effectuant les calculs de votre côté. Consultez le guide pour créer vos propres rapports dans la documentation développeur Intercom.

Si vous regardez les rapports de conversations disponibles dans l'interface utilisateur par rapport aux rapports extraits via l'API conversations, vous pouvez remarquer une différence dans le nombre de conversations. Cela s'explique par le fait que les tickets back office associés à une conversation sont inclus lorsqu'ils sont extraits via l'API.

Pour résoudre ce problème, vous pouvez filtrer les résultats après les avoir récupérés via les API list conversations, retrieve a conversation, ou search for conversations, et séparer les tickets des conversations en utilisant le champ ticket dans la réponse de l'API conversation. Le champ ticket sera rempli avec un objet s'il s'agit d'un ticket et sera nul s'il s'agit d'une conversation.

Les webhooks vous permettent de vous abonner à des notifications en temps réel des événements se produisant dans Intercom, comme lorsqu'un contact est créé ou qu'un message entrant est reçu.

Vous pouvez voir les webhooks disponibles pour chaque version dans notre documentation développeur. Une fois que vous avez identifié le webhook dont vous avez besoin, suivez ce guide pour les configurer.

Il n'y a pas de plans pour ajouter de nouveaux webhooks dans notre feuille de route, mais si votre équipe a besoin d'un webhook, veuillez soumettre une demande à l'équipe ou l'ajouter à la liste de souhaits produit dans la communauté Intercom.

Lors de la création sur les webhooks Intercom, gardez à l'esprit les points suivants :

Les API Intercom pour lister et rechercher des ressources offrent une pagination basée sur un curseur. Cela permet, lorsque vous demandez une grande quantité de données — comme de nombreuses conversations avec toutes leurs parties — de les recevoir et de les traiter en plus petits morceaux.

Pour des exemples d'utilisation de la pagination avec les API de liste Intercom, qui acceptent des paramètres de chemin, et les API de recherche, qui utilisent des paramètres de requête, consultez notre guide de pagination.

Pour la pagination basée sur un curseur, Intercom utilise un pointeur qui fait référence à un enregistrement spécifique en fonction de la limite que vous définissez par le nombre de pages que vous spécifiez par requête.

Lorsqu'il est renvoyé dans un objet, le pointeur ressemble à quelque chose comme 'WzXXXXXXXXXXXXXX'.

Vous pouvez ensuite utiliser le pointeur de la réponse pour effectuer la requête suivante pour le lot de données suivant.

Le formatage de la pagination dans la requête diffère légèrement entre les API de liste et les API de recherche, mais les réponses fonctionnent de la même manière.

Vous pouvez voir des exemples de requêtes curl sur notre page Pagination, et des tutoriels sur l'utilisation des API de liste et des API de recherche.

Toutes les applications qui interagissent avec les données d'un espace de travail tiers et les applications construites avec Canvas Kit nécessitent OAuth. Vous ne devez jamais demander aux users leur jeton d'accès et utiliser uniquement OAuth pour interagir avec leurs données.

Consultez la documentation pour les instructions pour configurer OAuth.

Vous devrez configurer OAuth si vous créez une intégration avec Intercom qui accède aux données Intercom d'autres personnes. Cela inclut les applications publiques que vous prévoyez de lister sur la boutique d'applications Intercom ainsi que les applications et intégrations que vous demanderez aux users d'installer via votre propre site web. En savoir plus sur OAuth dans notre documentation développeur.

Si vous accédez uniquement aux données de votre propre espace de travail Intercom, vous pouvez utiliser un jeton d'accès.

Si vous créez une application privée qui accède uniquement aux données de votre espace de travail Intercom, vous pouvez utiliser votre jeton d'accès Intercom pour l'authentification. Trouvez votre jeton d'accès dans votre developer hub et en savoir plus sur l'authentification ici.

Vous pouvez utiliser votre jeton d'accès Intercom si vous utilisez l'API pour accéder aux données de votre propre espace de travail Intercom. Trouvez votre jeton d'accès dans votre developer hub et en savoir plus sur l'authentification ici.

Pour trouver votre jeton d'accès API, suivez ces étapes :

Oui, le support Intercom peut faire pivoter l'OAuth Client Secret de votre application sur demande. Une fois pivoté, l'ancien secret est immédiatement invalidé et le nouveau secret est disponible dans le Developer Hub.

Pour demander une rotation, contactez le support Intercom avec les détails de votre application. Assurez-vous que votre équipe est prête à mettre à jour la configuration de votre intégration avec le nouveau secret immédiatement, car l'ancien secret ne sera plus valide dès la rotation effectuée.

Vous pouvez créer une app pour votre Intercom Inbox en utilisant Canvas Kit, un kit d'outils qui vous permet de créer des apps fonctionnant directement dans l'interface Intercom.

Suivez ce tutoriel pour apprendre à créer votre première app Inbox. Vous pouvez aussi en savoir plus sur Canvas Kit et trouver la documentation de référence dans notre documentation développeur.

Vous pouvez créer une app pour votre Intercom Messenger en utilisant Canvas Kit, un kit d'outils qui vous permet de créer des apps fonctionnant directement dans l'interface Intercom.

Notez que les personnalisations sont limitées à ce que Canvas Kit permet et doivent être créées dans le Messenger : il n'est pas possible de recréer ou de modifier l'apparence du Messenger.

Suivez ce tutoriel pour apprendre à créer votre première app Inbox. Vous pouvez aussi en savoir plus sur Canvas Kit et trouver la documentation de référence dans notre documentation développeur.

Si vous visitez la page Test & Publish > Vos Workspaces de votre app dans le Developer Hub, vous devriez voir tous les espaces de travail dont vous êtes membre (en tant que coéquipier Intercom).

Vous pouvez cliquer sur Installer l'app à côté de l'espace de travail sur lequel vous souhaitez installer l'app donnée. Cette app sera alors installée et un Access Token sera fourni pour cet espace de travail afin que vous puissiez accéder à ses données via l'API.

Pour les instructions d'installation tierces, consultez notre documentation développeur.

Lorsque vous êtes prêt à publier votre app, vous pouvez suivre les étapes dans le developer hub. Vous trouverez un guide sur la publication de votre app dans notre documentation développeur.

Le SDK Intercom (Software Development Kit) pour iOS vous permet d'utiliser le Intercom Messenger dans votre app, d'avoir des conversations avec vos clients, d'envoyer des messages sortants enrichis, d'afficher votre Help Center et de suivre des événements.

Vous pouvez installer Intercom pour iOS en utilisant Cocoapods, Swift Package Manager ou manuellement. Lisez le guide complet d'installation iOS. Vous pouvez trouver Intercom pour iOS sur GitHub ainsi qu'une app exemple pour explorer le SDK.

Le SDK Intercom pour Android vous permet d'utiliser le Intercom Messenger dans votre app, d'avoir des conversations avec vos clients, d'envoyer des messages sortants enrichis, d'afficher votre Help Center et de suivre des événements.

Vous pouvez installer Intercom pour Android en utilisant Gradle ou manuellement. Lisez le guide complet d'installation Android. Vous pouvez trouver Intercom pour Android sur GitHub ainsi qu'une app exemple pour explorer le SDK.

Le wrapper Intercom React Native vous permet d'utiliser Intercom pour iOS et Intercom pour Android dans vos apps React Native. Suivez le guide d'installation React Native pour commencer.