A practical guide to the Intercom JavaScript API

The Intercom Messenger is pretty great right out of the box. It lets you chat with customers on your site or in your app, which is a huge win. But what happens when you want it to do... more? Maybe you want the chat widget to pop up at a specific moment, or you want to track exactly what your users are doing to offer better help.

That's where the Intercom JavaScript API steps in.

This guide is for anyone who's looked at their Messenger and thought, "I wish I could tweak this." We'll cover what the API is, what you can actually do with it, and, maybe most importantly, where it falls short. By the end, you'll get the full picture and see how you can get the same results (or better) with a lot less heavy lifting.

What is the Intercom JavaScript API?

So, what is this thing, really? The Intercom JavaScript API is basically a set of commands your developers can use to boss the Messenger around. It's like having a remote control for that little chat bubble, letting you tell it when to show up, what to say, and who it's talking to.

You can break down its main jobs into a few key areas:

• Customizing the experience: You get to control how the Messenger looks and behaves. Want it to act differently for paying customers versus free trial users? You can do that. Want it to hide on certain pages? No problem.

• Tracking user data: The API lets you send information about your users and their actions straight to Intercom. When someone upgrades their plan or clicks a specific button, you can log that event. This builds up a detailed customer profile, which is gold for your support team.

• Managing sessions: This one sounds a bit technical, but it's crucial. It lets you manage when a user's session starts and stops, which is especially important for modern web apps and making sure conversations stay private when a user logs out.

All of this happens on the "client-side," which is just a fancy way of saying the code runs in your user's web browser. That's what gives you the power to change their experience on the fly.

Key capabilities of the Intercom JavaScript API

Okay, let's talk about what you can actually do with this API. It has a whole menu of methods, but they mostly boil down to a few core jobs.

Controlling the Messenger's look and feel

One of the biggest use cases is simply controlling the Messenger widget. You can make it appear or disappear based on a user's actions, which is perfect for offering help at just the right time.

Here are a few of the most common commands:

• "Intercom('show')" and "Intercom('hide')": These do exactly what they sound like. You can use them to pop the Messenger open when someone clicks a "Need help?" button on your site, for instance.

• "Intercom('showSpace', spaceName)": This handy command lets you open a specific part of the Messenger. You can send someone straight to your help center ("help"), their existing conversations ("messages"), or the Messenger's home screen ("home").

• "Intercom('showNewMessage', 'pre-populated content')": This one opens up a new message composer. Even better, you can pre-fill it with text to get the conversation started, like "I have a question about my recent order..."

A screenshot of the Intercom Messenger, showcasing its modern design and live chat functionality that can be controlled by the Intercom JavaScript API.

Managing user sessions and data

This is a big one, especially for security and keeping user data straight in modern web apps.

These are the must-know methods for handling sessions:

• "Intercom('boot', {...})": This command boots up Intercom and tells it who the user is. It's non-negotiable for single-page apps where the page doesn't do a full refresh as people navigate around.

• "Intercom('update', {...})": Need to update a user's info without a page reload? This is your command. If a customer upgrades to a premium plan, you can use "update" to instantly send that "plan: 'premium'" detail over to Intercom.

• "Intercom('shutdown')": Please, please use this one. When a user logs out of your app, you have to call "shutdown". It clears their Intercom session and conversation history from the browser. If you forget, the next person to use that computer could see their private chats. Yikes.

Your developers need to be really careful to call these commands at the right time, on login, on logout, or whenever a user's data changes.

Tracking user events

Event tracking is your way of telling Intercom what your users are up to. It's incredibly powerful for seeing how people use your product and sending them relevant messages.

The main command for this is "Intercom('trackEvent', 'event-name', {metadata})".

For instance, if a user signs up for a webinar, you could send this event:

"Intercom('trackEvent', 'signed-up-for-webinar', { webinar_topic: 'Advanced Reporting' });"

That event gets logged on the user's profile in Intercom. From there, you can create segments (like "everyone who signed up for the reporting webinar") and send them targeted follow-ups. But here's the thing: the API only sends the event. The logic for what happens next has to be built somewhere else, either in Intercom's campaign tools or with more custom code.

How to get started with the Intercom JavaScript API

Let's be clear: this isn't a point-and-click setup. To get the Intercom JavaScript API working, you're going to need a developer. It involves digging into your website's code, so it's not something a support or marketing manager can usually tackle alone.

There are a few different ways a dev can get it installed:

1. The classic JavaScript snippet: This is the copy-and-paste method. You grab a chunk of code from your Intercom settings and drop it into the HTML of your website. It's a solid choice for more traditional sites where every click loads a brand-new page.

2. The NPM package: If your site is a modern single-page application built with something like React or Vue, this is the way to go. It’s a much cleaner and more organized way to weave Intercom into your codebase.

3. Tag managers: You can also load Intercom through tools like Google Tag Manager or Segment. If your company already uses one of these to manage all your third-party scripts, this will probably be the easiest path.

How do you choose? It really comes down to your website's tech stack. For old-school sites, the snippet works. For modern apps, the NPM package is best. If you're already all-in on a tag manager, stick with that.

Whichever route you take, you'll need your "app_id" from your Intercom settings. It's the key that tells the Messenger which workspace to connect to.

The downsides of the Intercom JavaScript API

So far, the API sounds pretty useful, right? It is. But leaning on it for everything can lead to some major headaches. These are the real-world problems that teams hit over and over.

You're completely reliant on developers

Any time you want to change something, track a new event, tweak a workflow, add a new proactive message, you have to file a ticket and wait for a developer. As many people in the Intercom community forums find out, this creates a massive bottleneck. Your support team might have brilliant ideas, but they're stuck in the engineering backlog. So much for moving quickly.

Your website code gets messy

The API only provides the triggers. The intelligence has to live somewhere. If you want a workflow like, "Only show this message if a customer is on the premium plan and has viewed the billing page three times," a developer has to hard-code that logic right into your website. Soon enough, your app's codebase is littered with brittle, support-specific rules that are a pain to maintain.

It's not smart

The API is a puppet; it only does what you pull the strings to make it do. It has zero ability to understand what a user is actually asking. It can't learn from old conversations, figure out the intent behind a question, or find an answer on its own. Every single interaction has to be meticulously planned and coded beforehand.

It can't access all your data

Since the API runs in the user's browser, it can only see data that's available in the browser. What if you need to access a customer's order history from your database or check their server settings? A developer has to build a whole separate system just to fetch that data from your backend and pipe it into Intercom. It's a ton of work for something that feels like it should be simple.

Is there a better automation alternative to the Intercom JavaScript API?

After reading about all those limitations, you might be wondering if you're stuck between doing nothing or hiring another developer. Luckily, there's another option. Instead of coding every workflow by hand, you can use an AI layer that plugs right into your existing tools and does the hard work for you.

This is exactly what we built eesel AI to do. It connects to Intercom, your help docs, and other apps to give you smart automation without writing a line of custom code.

Here's how that solves the headaches we just talked about:

• Get started in minutes, not months: Remember that developer bottleneck? Gone. A support manager can set up eesel AI on their own with a one-click integration. You can finally move at the speed of your customers, not your engineering team's schedule.

• You're in control (no code needed): Instead of explaining a complex workflow to a dev, you can build it yourself in eesel AI's visual editor. You can set rules for how the AI should behave, what its persona is, and what actions it can take, like looking up an order in Shopify or assigning a ticket to the right team. All the power, none of the code.

A screenshot of the customization and action workflow screen in eesel AI, a simpler alternative to the Intercom JavaScript API.

• Connect all your knowledge: The JavaScript API is stuck with browser data, but eesel AI can connect to everything. It learns from your help center, past conversations, internal wikis in Confluence, documents in Google Docs, and more. That means it can give complete answers, not just partial ones.

• Test before you launch: How do you know if a new, custom-coded workflow will actually work? You cross your fingers and hope for the best. With eesel AI, you can run a simulation on thousands of your past tickets to see exactly how the AI would have performed. You get real data on its resolution rate before you turn it on for your customers.

The eesel AI simulation dashboard showing how AI predicts future support automation rates, a feature not available with the standard Intercom JavaScript API.

Should you use the Intercom JavaScript API?

The Intercom JavaScript API is a solid tool for developers who need fine-grained control to build highly custom Messenger experiences. If you have the engineering resources to spare, you can do some really cool things with it.

But for most teams, relying on it for automation is a slow, expensive, and frustrating path. It creates a constant dependency on developers and makes it nearly impossible for support teams to experiment and improve things quickly.

If you want to move faster and build smarter support flows without the coding marathon, an AI layer is the way to go. A tool like eesel AI gives you a much faster and more flexible way to get world-class automation up and running, right inside the Intercom you already know.

Ready to see what AI can do for your Intercom setup, no custom code required? Try eesel AI for free.