Passer au contenu principal

FAQ pour développeurs Intercom

Réponses aux questions fréquentes liées à notre documentation développeur, APIs, webhooks et applications.

Écrit par Phil Moore

Utilisez cet article pour configurer votre environnement développeur Intercom, configurer un domaine personnalisé Help Center avec SSL, authentifier votre application via des jetons d'accès ou OAuth, et gérer 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.


Configuration d'Intercom

Comment créer un compte développeur ?

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/

Comment configurer un domaine personnalisé pour le help center ?

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 « not found » après la configuration d'un domaine personnalisé, vérifiez votre enregistrement CNAME pour vous assurer que votre sous-domaine pointe vers le bon hôte Intercom : • 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.

Comment configurer SSL ?

SSL (ou TLS) est la méthode la plus utilisée pour sécuriser la connexion entre votre serveur et votre navigateur. Elle garantit que la connexion 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é :

  • Utiliser un SSL flexible (avec un fournisseur DNS tiers comme CloudFlare ou AWS CloudFront)

  • Utiliser votre propre certificat SSL (avec un proxy de terminaison TLS)

Intercom gère-t-il les certificats SSL pour les domaines personnalisés ?

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.

Note : HTTPS (quick setup) n'est pas disponible par défaut pour tous les espaces de travail - c'est un paramètre que notre équipe Support peut activer pour vous. Une fois activé, l'option HTTPS (quick setup) apparaîtra dans les paramètres de votre Help Center. Suivez les instructions de configuration DNS ci-dessous pour finaliser votre configuration.

Comment activer HTTPS (quick setup) pour votre domaine personnalisé

Si vous souhaitez passer votre domaine personnalisé en HTTPS :

  1. Allez dans Paramètres > Help Center > Configurer & Style.

  2. Rendez-vous dans la section Domaine .

  3. Sélectionnez HTTPS (quick setup) comme protocole de sécurité et enregistrez les modifications.

  4. Une fois activé, assurez-vous que votre enregistrement CNAME pointe vers [us.intercomhelpcenter.com](https://us.intercomhelpcenter.com) (ou [eu.intercomhelpcenter.com](https://eu.intercomhelpcenter.com) pour les régions EU) via votre fournisseur de domaine. Vous recevrez un email de confirmation lorsque la configuration sera réussie, généralement sous 48 heures.

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 peuvent varier.

Dépannage avancé

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 :

  • HTTPS par défaut en configuration manuelle : Référez-vous à notre Guide des domaines personnalisés pour des étapes de configuration précises.

  • Le domaine s'affiche comme « Non sécurisé » : Pour sécuriser votre help center hébergé en HTTP, envisagez :

    • Utiliser un fournisseur DNS tiers, comme Cloudflare ou AWS CloudFront, pour un proxy SSL flexible.

    • Employer un proxy de terminaison TLS pour une gestion avancée des certificats SSL.

Problèmes courants HTTPS/SSL et dépannage

1. Domaine non sécurisé

  • Assurez-vous que seul le certificat SSL d'Intercom est actif pour votre domaine. Supprimez ou désactivez tout certificat supplémentaire de votre hébergeur ou CDN (Content Delivery Network).

  • Si vous utilisez un CDN comme Cloudflare, réglez le statut du proxy sur « DNS only » (icône nuage gris).

  • Vérifiez que votre enregistrement DNS CNAME pointe vers le bon point d'accès Intercom (us.intercomhelpcenter.com pour les US, eu.intercomhelpcenter.com pour l'UE).

Erreur ERR_SSL_VERSION_OR_CIPHER_MISMATCH

  • Vérifiez que votre enregistrement CNAME (Canonical Name) pointe vers [us.intercomhelpcenter.com](https://us.intercomhelpcenter.com).

  • Confirmez qu'aucun enregistrement DNS (Domain Name System) en conflit n'existe. Un seul CNAME doit être actif pour l'entrée de domaine. Supprimez les doublons.

  • Assurez-vous que la propagation DNS, qui peut prendre jusqu'à 72 heures, est terminée. Vous pouvez utiliser des outils comme whatsmydns.net pour vérifier la propagation globale.

2. Configuration HTTPS bloquée en attente

  • Vérifiez les problèmes courants de configuration DNS, comme des erreurs de format dans l'enregistrement CNAME (par exemple, ajout accidentel de .yourdomain.com) ou l'utilisation d'un type d'enregistrement incorrect (par exemple, un enregistrement A au lieu de CNAME).

  • Assurez-vous que l'enregistrement CNAME pointe vers us.intercomhelpcenter.com (ou eu.intercomhelpcenter.com pour les régions de l'UE).

  • Après corrections, attendez la propagation DNS, qui peut prendre jusqu'à 72 heures. Utilisez whatsmydns.net pour vérifier la propagation globale avant de tester à nouveau.

3. Option HTTPS (Configuration rapide) non disponible

  • Contactez le support Fin pour activer la configuration rapide HTTPS pour votre espace de travail — elle n'est pas disponible par défaut.

  • Assurez-vous que votre domain n'est pas déjà utilisé par un autre compte Intercom.

  • Vérifiez qu'un enregistrement CNAME a été ajouté chez votre fournisseur DNS, pointant vers us.intercomhelpcenter.com.

4. Erreur d'accès refusé

  • Vérifiez que l'enregistrement CNAME pointe correctement vers us.intercomhelpcenter.com.

  • Si vous utilisez Cloudflare, réglez SSL sur « Flexible » ou « Full » — évitez « Full (Strict) ».

  • Désactivez puis réactivez la configuration SSL pour relancer la séquence de provisionnement SSL.


Help Center URL et gestion du domain

URLs cassées après migration

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

  • Créez un nouvel article public pour remplacer l'URL cassée.

  • Mettez à jour tous les appels à l'action ou liens dans votre contenu pour pointer vers la nouvelle URL de l'article.

Erreur « Not found » lorsque les articles semblent corrects en interne

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

  • Vérifiez si votre Help Center est réglé sur Live dans vos paramètres.

  • Allez dans Paramètres > Help Center et réglez le statut sur Live pour rendre l'URL publique accessible.


L'API Intercom

Quelle est la version actuelle de l'API ?

La version actuelle de l'API est 2.18. 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 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.

Note : La documentation pour développeurs conserve aussi des pages de référence pour l'ancienne API 1.x (URLs contenant /docs/references/1.0/ ou /docs/references/1.1/). Ces pages décrivent des endpoints tels que /users et /leads qui ne sont pas utilisés dans la version 2.x. Assurez-vous de suivre les pages de référence de la version actuelle sous /docs/references/rest-api/.

Quels endpoints sont disponibles dans la version actuelle de l'API ?

Les endpoints clés disponibles dans la version 2.18 de l'API Intercom incluent ceux ci-dessous. Des APIs plus récentes, telles que Folders, Dynamic Content, Roles, Auth Tokens, et Granted Companies, sont aussi disponibles en 2.18. Pour la liste complète, consultez la référence API.

Puis-je déclencher l'ouverture d'un article dans le Messenger depuis un bouton ?

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.

Comment déclencher un article depuis du HTML

# You can add a link anywhere on your site to open an article in the Messenger: 

<a href="#" onclick="Intercom('showArticle', 123)">Open article</a>


Contacts

Dois-je utiliser le point de terminaison /users ou /contacts ?

Utilisez /contacts. Dans l'API actuelle, users et leads sont tous deux des contacts, et vous les créez ou mettez à jour avec les points de terminaison Créer un contact (POST /contacts) et Mettre à jour un contact (PUT /contacts/{id}). POST /users est un point de terminaison hérité de la version 1.x et ne fonctionne pas avec les versions actuelles de l'API.

Comment créer un contact sans adresse e-mail ?

Un contact doit avoir au moins un e-mail ou un external_id. Pour créer un user sans e-mail, envoyez votre propre identifiant unique pour lui en tant que external_id. Dans les points de terminaison /contacts, ce champ s'appelle external_id, pas user_id. Envoyer user_id sans e-mail renvoie l'erreur either_email_or_user_id_present validation failed.

POST https://api.intercom.io/contacts

{
"external_id": "cust_001",
"name": "Jane Doe",
"custom_attributes": {
"Currency": "EUR"
}
}

Tous les attributs personnalisés que vous définissez doivent déjà exister dans Paramètres > Données > Personnes, sinon la requête renvoie une erreur indiquant que l'attribut n'existe pas.

Puis-je créer des users en masse via l'API ?

Oui. Dans Intercom, les users sont considérés comme des contacts. Vous pouvez utiliser le point de terminaison de création en masse de contacts pour créer plusieurs contacts en une seule requête. Sinon, vous pouvez utiliser le point de terminaison de création de contact dans un script qui importe les users un par un, ou suivre ce tutoriel pour des exemples de code afin de 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. Voir Quelles sont les limites de débit actuelles ? ci-dessous pour les limites applicables aux applications publiques et privées.

Opérations en masse et leurs limites

Pour importer des contacts à grande échelle, utilisez le point de terminaison de création en masse de contacts, ou le point de terminaison de création de contact dans une boucle avec une gestion appropriée des limites de débit. Assurez-vous que votre script respecte les limites de débit.

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 export/import manuel :

  • Exportation en masse de conversations (utilisez le point de terminaison d'exportation de données pour les exportations de données de conversation)

  • Suppression en masse de notes (les notes doivent être supprimées une par une depuis l'interface du workspace)

Comment puis-je récupérer les données d'un user archivé ?

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 de désarchivage de contact si vous avez l'ID du contact.

Vous pourrez ensuite accéder aux données du contact via le point de terminaison API pour obtenir un contact et à leurs conversations via le point de terminaison API pour récupérer une conversation.

Il n'est pas possible de désarchiver un user ou un contact depuis l'interface, cela doit être fait via l'API.

Puis-je supprimer des notes sur mes contacts via l'API ?

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 le workspace, mais une par une seulement.


Conversations

Comment assigner des conversations à une équipe via l'API ?

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 admin ou une équipe en utilisant le point de terminaison API de gestion d'une 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 d'exécution des règles d'assignation sur une conversation. Vous devez avoir accès à l'ID Intercom provisionné pour la conversation.

Vous pouvez tester cette fonctionnalité depuis la fonctionnalité « Try It » dans notre documentation développeur, la collection Postman Intercom, 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.

Comment ajouter des notes aux conversations via l'API ?

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 de réponse à une conversation. Vous devrez choisir un message_type de note et un type « admin » ainsi que l'admin_id dont la note doit provenir.

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

Comment ajouter des tags aux conversations via l'API ?

Si vous avez déjà créé un tag dans l'interface, 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 d'ajout de tag à une conversation, vous devez 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 fonctionnalité « Try It » dans notre documentation développeur, la collection Postman Intercom, ou dans votre propre terminal ou IDE. N'oubliez pas d'utiliser votre jeton d'accès Intercom comme jeton bearer.

Comment créer une conversation via l'API ?

Vous pouvez créer une conversation depuis l'API initiée par un contact (c'est-à-dire un user ou lead) en utilisant le point de terminaison API de création de 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 message lors de la requête.

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

Par défaut, une conversation créée de cette manière n'apparaîtra pas dans l'Inbox — et ne sera pas recherchable via la recherche de Conversation — tant que le contact n'y aura pas répondu. Pour faire apparaître la conversation immédiatement dans l'Inbox, sans attendre la réponse du contact, incluez « create_conversation_without_contact_reply » : true dans la charge utile de la requête. Cela vaut false par défaut si non fourni.

Que faire si la conversation n'apparaît pas du tout, même avec un ID ?

Si le champ body de la charge utile de la requête est manquant, vide ou mal formé, l'API peut quand même renvoyer une réponse de succès et créer une coquille de conversation sans contenu de message attaché. Comme l'Inbox ne peut pas afficher une conversation sans messages, l'ouvrir dans l'interface renvoie une erreur 404 (« Impossible de charger la conversation »), même si la conversation peut toujours être récupérée via l'API par ID. Si cela se produit, vérifiez que le champ body de l'intégration est présent et non vide, et que message_type est correctement défini (par exemple inapp ou email). Une conversation cassée existante de ce type ne peut pas être récupérée — elle doit être recréée avec une charge utile corrigée.

Comment supprimer des conversations avec l'API ?

Pour fermer une conversation via l'API, vous pouvez utiliser le point de terminaison API de gestion d'une conversation. Vous aurez besoin de l'ID Intercom provisionné de la conversation, de votre admin_id et d'utiliser un message_type « close ».

Si vous devez uniquement expurger une certaine partie de la conversation, utilisez le point de terminaison API d'expurgation d'une partie de conversation.

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

Comment configurer des notifications personnalisées lorsqu'un coéquipier est assigné à une conversation ?

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 de 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é.

Comment accéder aux conversations secondaires via l'API ?

Les conversations secondaires n'ont pas leur propre 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'utilisateur dans la conversation secondaire.


Tickets

Comment créer un ticket en utilisant l'API ?

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 de notre documentation développeur pour créer un type de ticket et créer un nouveau ticket.

Comment puis-je signaler les tickets back office pour qu'ils ne soient pas comptabilisés lors de l'utilisation de l'API ?

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 filtrer de la même manière 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.


Codes et messages d'erreur

Que signifie un message d'erreur 403 API Plan restricted dans une réponse ?

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 pouvez trouver une liste complète des codes d'erreur et des réponses HTTP dans notre documentation développeur.

Que signifie un message d'erreur 409 conflict dans une réponse ?

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 external_id. Vous pouvez trouver une liste complète des codes d'erreur et des réponses HTTP dans notre documentation développeur.

Que signifie un message d'erreur 429 dans une réponse ?

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é. Voir Quelles sont les limites de taux actuelles ? pour les limites par défaut des applications publiques et privées. 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 des limites de taux pour vous assurer de ne pas atteindre la limite. Vous pouvez trouver une liste complète des codes d'erreur et des réponses HTTP dans notre documentation développeur.

Quelles sont les limites de taux actuelles ?

Les applications privées ont une limite de taux par défaut de 10 000 appels API par minute par espace de travail, partagée par toutes les applications privées dans l'espace de travail. Cela signifie que si un espace de travail a plusieurs applications privées installées, chacune contribue au même total.

Les applications publiques ont une limite de taux par défaut de 10 000 appels API par minute pour chaque application et de 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.


Rapports

Pourquoi mon rapport est-il différent lorsqu'il est extrait de l'API par rapport à l'interface utilisateur ?

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 soit les paramètres de requête de l'API pour correspondre au fuseau horaire de votre espace de travail, soit changez 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.

Les tickets back office sont-ils comptabilisés dans les statistiques lors de l'extraction d'un rapport via l'API ?

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 est dû au 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 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.


Webhooks

Quels webhooks sont disponibles ?

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.

Y a-t-il des plans pour ajouter de nouveaux webhooks ?

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.

Fiabilité et livraison des webhooks

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

  • Politique de nouvelle tentative : Intercom réessaie les livraisons de webhook échouées. Si votre point de terminaison renvoie une réponse non 2xx, Intercom réessaiera la requête. Concevez votre point de terminaison pour gérer les livraisons en double (rendez-le idempotent).

  • Délai d'attente : Votre point de terminaison doit répondre dans un délai court. En cas de dépassement, la livraison est considérée comme un échec et réessayée.

  • Ordre : Les événements webhook ne sont pas garantis d'arriver dans l'ordre exact où ils se sont produits. Utilisez les horodatages des événements pour séquencer correctement les événements dans votre système.

  • Débogage : Le Developer Hub n'affiche pas l'historique des livraisons de webhook ni les charges utiles envoyées. Pour déboguer les événements manqués ou mal formés, enregistrez les requêtes entrantes sur votre propre point de terminaison, y compris le sujet, l'ID de notification et le code de réponse que vous renvoyez. Dans le Developer Hub, sous les paramètres webhook de votre application, vous pouvez prévisualiser un exemple de charge utile pour chaque sujet, et enregistrer vos paramètres webhook envoie une requête de test à l'URL de votre point de terminaison pour confirmer qu'il peut recevoir les notifications. Si vous avez besoin d'aide pour enquêter sur des livraisons spécifiques, contactez Fin Support.


Pagination

Comment fonctionne la pagination ?

Les API Intercom pour lister et chercher 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.

Comment utiliser le champ starting_after ?

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.

La mise en forme 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 list APIs, et des search APIs.


Authentification

Quel type d'authentification est requis pour les applications publiques ?

Toutes les applications qui interagissent avec les données d'un espace de travail tiers et les applications construites avec Canvas Kit nécessitent la mise en place d'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.

Dois-je utiliser OAuth pour mon application ?

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 l'Intercom app store 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.

Quel type d'authentification est requis pour les applications privées ?

Si vous créez une application privée qui n'accède qu'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.

Où puis-je trouver mon jeton d'accès Intercom ?

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 :

  1. Ouvrez le Intercom Developer Hub.

  2. Naviguez vers Your Apps dans Developer Hub > Settings > Your Apps. Vous devriez voir une liste d'applications associées à votre espace de travail.

  3. Localisez votre application privée, qui peut inclure le nom de votre espace de travail et parfois le suffixe « Access Token App. »

  4. Cliquez sur le nom de l'application pour ouvrir ses détails.

  5. Allez à la section Authentication pour trouver le jeton. Traitez ce jeton comme un mot de passe, car il est privé et ne doit pas être partagé.

Puis-je faire pivoter ou changer mon OAuth Client Secret ?

Vous ne pouvez pas faire pivoter vous-même le OAuth Client Secret de votre application, mais notre équipe de support peut le faire pour vous sur demande. Une fois qu'il est fait, l'ancien secret cesse de fonctionner immédiatement et le nouveau secret est disponible dans le Developer Hub.

Important : L'ancien secret est invalidé immédiatement après la rotation. Soyez prêt à mettre à jour la configuration de votre intégration dès que la rotation a lieu pour éviter toute interruption de service.

Pour demander une rotation, envoyez-nous un message dans le Messenger et demandez à parler à l'équipe de support. Incluez le nom de votre application et l'ID client, et convenez d'un horaire pour la rotation afin que votre équipe puisse mettre à jour la configuration de votre intégration avec le nouveau secret immédiatement.


Installation et publication des applications

Comment créer une application pour mon Inbox ?

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 également en savoir plus sur Canvas Kit et trouver des documents de référence dans notre documentation développeur.

Comment créer une application pour mon Messenger ?

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 qui est possible via Canvas Kit et doivent être créées dans le Messenger : il n'est pas possible de recréer ou de re-skinner le Messenger.

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

Comment installer mon application ?

Si vous visitez la page Test & Publish > Your Workspaces de votre application dans le Developer Hub, vous devriez voir tous les espaces de travail dont vous (en tant que membre Intercom) faites partie.

Vous pouvez cliquer sur Install app à côté de l'espace de travail sur lequel vous souhaitez installer l'application donnée. Cette application 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.

Comment puis-je publier mon application sur l'Intercom app store ?

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.


Messenger

Comment installer le Messenger pour iOS ?

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 riches, 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.

Comment installer le Messenger pour Android ?

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 riches, 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.

Comment installer le Messenger pour React Native ?

Le wrapper React Native d'Intercom 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.

Avez-vous trouvé la réponse à votre question ?