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, et la résolution 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 allant 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 « non trouvé » 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 SSL manuellement — 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 Help Center :

1. Domaine non sécurisé

ERR_SSL_VERSION_OR_CIPHER_MISMATCH Erreur

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 avoir déplacé le 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 :

Si vous rencontrez un comportement inattendu dans votre Help Center, commencez par ces étapes avant d'examiner la configuration :

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 également changer la version utilisée par votre application dans votre Developer Hub en suivant les étapes listé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 showArticle méthode de l'API JavaScript. L'article s'ouvrira dans le Messenger et cliquer sur le bouton retour du Messenger ramènera au contexte précédent. Si le Messenger est fermé lors de l'appel de la méthode, 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 considérés comme des 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 mettre en place 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.

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 API unarchive contact si vous avez l'ID du contact.

Vous pourrez ensuite accéder aux données du contact via le point de terminaison API get a contact et à leurs conversations via le point de terminaison API retrieve a conversation.

Non, il n'est actuellement pas possible de supprimer des notes individuelles ou en masse sur les 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 API manage a conversation. Vous devez avoir accès à l'ID Intercom provisionné pour 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 API run assignment rules on a conversation. Vous devez avoir accès à l'ID Intercom provisionné pour la conversation.

Vous pouvez tester cette fonctionnalité depuis la fonction "Try It" dans notre documentation développeur, la collection Intercom Postman, ou dans votre terminal ou IDE. 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 API reply to a conversation. Vous devrez choisir un message_type de note et un type "admin" ainsi que l'admin_id d'où la note doit provenir.

Vous pouvez tester cette fonctionnalité depuis la fonction "Try It" dans notre documentation développeur, la collection Intercom Postman, ou dans votre 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 via l'API.

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

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

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

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

Vous pouvez tester cette fonctionnalité depuis la fonction "Try It" dans notre documentation développeur, la collection Intercom Postman, ou dans votre 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 API manage a conversation. Vous devrez avoir l'ID Intercom provisionné de la conversation, votre admin_id et utiliser un message_type "close".

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

Vous pouvez tester cette fonctionnalité depuis la fonction "Try It" dans notre documentation développeur, la collection Intercom Postman, ou dans votre 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 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 préféré.

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 affichées 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 le 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 API search tickets. 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 qui leur est 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 devrez 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 pour développeurs.

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 pour développeurs.

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 pour développeurs.

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 pour développeurs.

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 pour développeurs.

Si vous créez vos propres rapports en utilisant l'API, vous pouvez remarquer certaines 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 seront 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 l'API list conversations,API retrieve a conversation, ouAPI 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 pour développeurs. 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.

Les APIs 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 APIs de liste Intercom, qui acceptent des paramètres de chemin, et les APIs 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 prochain lot de données.

Le formatage de la pagination dans la requête diffère légèrement entre les APIs de liste et les APIs 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 APIs de liste et des APIs 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 pour développeurs.

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 hub développeur 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 hub développeur et en savoir plus sur l'authentification ici.

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

Oui, Intercom Support peut faire pivoter le 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 Intercom Support 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 application pour votre Intercom Inbox en utilisant Canvas Kit, un kit d'outils qui vous permet de créer des applications fonctionnant directement dans l'interface Intercom.

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

Vous pouvez créer une application pour votre Intercom Messenger en utilisant Canvas Kit, un kit d'outils qui vous permet de créer des applications 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 application Inbox. Vous pouvez aussi en apprendre plus sur Canvas Kit et trouver la documentation de référence dans notre documentation développeur.

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

Vous pouvez cliquer sur Install app à côté du workspace sur lequel vous souhaitez installer l'application donnée. Cette application sera alors installée et un Access Token sera fourni pour ce workspace 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 application, vous pouvez suivre les étapes dans le developer hub. Vous trouverez un guide sur la publication de votre application dans notre documentation développeur.

Le SDK Intercom (Software Development Kit) pour iOS vous permet d'utiliser le Intercom Messenger dans votre application, 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 application exemple pour explorer le SDK.

Le SDK Intercom pour Android vous permet d'utiliser le Intercom Messenger dans votre application, 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 application exemple pour explorer le SDK.

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