Initial impressions of Intercom
Prior to starting on the project, I had little experience of Intercom. I’d seen it in use at a couple of clients, but only for customer chats, not the knowledge bases. I did, however, have experience with articles in Zendesk and Freshdesk.
My first impressions were good. The structure was similar to Zendesk, with articles organized into collections. The version my client had allowed nested collections (sub-collections), which makes things a lot easier when it comes to the information architecture.
Intercom has a familiar What You See Is What You Get (WYSIWYG) editor that, while limited, is common and straight-forward to use. Nothing unusual there. Cross-references rely on providing the published URL as the link target, so you will need to publish the target first and then get its URL. You can unpublish it afterwards if needed, which is important if the target isn’t supposed to go public just yet.
Publishing was also an intuitive experience, with the ability to publish articles or save them as drafts.
For anyone who has used any of the well-known customer support CMSs, everything is pretty familiar. I was able to start adding articles, editing existing ones, and reorganize the collections straight away.
But I did run into a few problems when the content was translated …
The mystery of the lost formatting
This problem had myself and the client’s team stumped. I had created articles with correct use of headings (1x h1, h2 for second-level headings, h3 for third-level headings) and also used the callouts that are available in the editor. I used these for notes and tips. But when the content went out to a translation system via API and then back into Intercom, the heading levels were all h1 and h2.
As time went by, I thought I was losing my marbles as I’d correct the articles again, only to lose the formatting shortly after publishing.
Eventually, Intercom support came up with the answer - the API does not support all the features in the editor. So it is worth checking out what the API supports before you implement a consistent plan for page structure.
On this particular project, it meant not using the callouts for notes and tips and just accepting that the heading levels would change. I try to keep all articles limited to main heading and 1 level of subsections, so it didn’t require a major rethink of the structure.
Collections not appearing in other languages
I reorganised the collections when I first started work on the project. Over time, as I got to know the content better and added more, I reorganised the collections again. But customers who used the translations reported that the collection pages were different in their language compared to the English version.
After some investigation, it turned out that the collections need to be renamed in each language for them to appear. So I had to display the supported languages on the Collections page and then add a translation for each collection. For that, I used a free online service to provide the translation (these will be later corrected, if necessary, by native speakers.
Once the collections had a name in the relevant language, they appeared on the translated Collections pages.
This is also something to remember when deleting articles or collections - you need to delete them in each of the translated languages too. Otherwise, you might have translated versions of deleted articles still available publicly.
Internal links not working in other languages
Another issue that cropped up is that internal links were not working in the translated versions. By internal links, I mean anchor links to other sections on the same page. I had initially used them to link bullet list items in the intro of an article to the matching subsection further down the page.
It seemed that this may also be a problem caused by sending the articles out for translation via API and then back in via API. I assume that each translated page keeps the same links, but the targets for those links either get stripped out via API or change in some way.
On the project I was working on, the client added the right-side navigation for the article, to provide access to subsections. With that in place, I could remove the internal links without affecting users’ fast access to subsections.
Conclusion
I quite like working in Intercom, but it is a shame the API doesn’t support all of the features that are available in the editor. That’s something to bear in mind if you are thinking about pushing the content out to another service and then back in to Intercom.
If other issues crop up, I’ll update the article. If you have used Intercom and run into some of the problems I’ve mentioned, I hope this article has helped. Even if it is only to explain why the problems occur.
