Intercom Tag Template – Documentation

Intercom is a powerful chat tool that has seen a lot of use across a vast multitude of sectors, driving user engagement whilst tracking key user events and chat results. With recent events and staff shortages, having an automated system to help handle customers is more important than ever.

Now Intercom certainly isn’t the only option out there nowadays, but it’s still one of the biggest players, and one of the key benefits is the fact they have a JavaScript API library that allows savvy users to send certain commands and events to Intercom and listen out for specific situations.

The problem however is not everyone has the confidence to dive into javascript API’s, and using it via Google Tag Manager requires a bunch of custom HTML tags. Not only that, but it can be hard to integrate with GTM in regards to having tags react to Intercom.

Today we would like to humbly introduce our Unofficial Intercom API Connector tag template, this tag allows you to harness these functions directly from Google Tag Manager. We wanted to streamline the process of these useful functions for the slightly less JavaScript savvy and have them available as tags based on whatever triggers someone has dreamed up.

User-uploaded Image
Add a caption

Tag Complexity

There are three main types of actions:


This includes simple commands to Intercom such as showing or hiding the chat window. These are simple in the fact you simply need to choose your API action to call.


Still relatively simple, but require some input from you, such as starting a tour requiring you provide a tour id or showing a new message requires the message you want to show. These also come with the option of posting dataLayer custom events (more on this in a moment).


This is essentially for sending structured data into Intercom, for example events, where you need to name and send your event, but can also include extra metadata information via a table format to really flesh out the interaction.

User-uploaded Image
Add a caption

Intercom Settings

We’ve also allowed any action you send to include edits to the Intercom settings object, meaning you can add data such as a userID or other such custom attributes to Intercom along with any action you decide to call the Intercom API for.

The only limitation here is that, like the event metadata, these only support simple data structures, so no attributes within attributes I’m afraid.

Keep in mind that this section is completely optional but allows for you to update the Intercom settings on the fly.

Nerd Alert: This always copies the current Intercom settings object, appends the new values to and then replaces the original window.intercomSettings.

Optional dataLayer Interaction:

We also added a checkbox on every action, which if ticked will pass dataLayer events when the action completes to further enrich your options:

User-uploaded Image
Add a caption

We wanted to create an increased sense of visibility within the GTM ecosystem, so when these actions are used we push a dataLayer event around what has just happened, this way you can also use these events as triggers as custom event triggers in and of themselves.

User-uploaded Image
Add a caption

There are two sub-options in regards to the dataLayer post, generic & custom:

  • Generic names the dataLayer events after the API commands itself, so all events would be “Intercom – trackEvent” for example.
  • Custom on the other hand customises these towards the values you have input, so if you named your event myEvent then the custom even push would show as “Intercom – myEvent”.

Use Case

So how does this work in practice? Let’s say you want to track a custom event in Intercom when a user completes an action on your site, you create an instance of our tag template and select the API action to be Send Event, then in the Value box, just add your event name, for example Tracking Event. Add the optional metaData and tick the Post to dataLayer box and select generic or custom if you so desire. Then it’s just time to set this tag to be triggered on the desired page or action.

If Intercom is present on the the page it will send this event through and on success will create a dataLayer event Intercom – trackEvent (if generic dataLayer push was chosen), or Intercom – Tracking Event (if you chose custom), you could then use this custom event as a trigger to run another tag, this time with the API action to be Open Intercom, which would open the Intercom message box after the user was tracked as having completed your Tracking Event.


Being a custom tag template this is pretty much ready to go as soon as you get it from the Template Gallery, that being said there are two main things to keep in mind.

  1. This won’t work correctly if Intercom is not on your sight, as it will be trying to call something that simply is not there.
  2. If you have Intercom hardcoded, ensure to load this tag on DOM ready (for the reason stated above). If you have Intercom installed via Google Tag Manager rather than hard coded on your sight, ensure that our tag template fires after Intercom has been deployed.

So head on over to the GTM Gallery and look for the Intercom API Connector (Unofficial) to get started with our newest creation.

Looking at how to install Intercom via Google Tag Manager?

We wanted to keep our tag permissions’ light and and hardcoded Intercom install friendly so our tag does NOT install Intercom for you. That being said there does seem to already be an Intercom Widget custom template on the GTM Gallery already that can do this for you, though we can’t vouch for how nice it plays with our template.

Failing that you can always install Intercom via GTM the old fashioned way, through a custom HTML tag containing your install snippet, triggered to fire on DOM ready/Page Load of the relevant pages you want it deployed upon.

Something along the lines of:



window.intercomSettings = {
    app_id: APP_ID

(function(){var w=window;var ic=w.Intercom;if(typeof ic==="function"){ic('reattach_activator');ic('update',w.intercomSettings);}else{var d=document;var i=function(){i.c(arguments);};i.q=[];i.c=function(args){i.q.push(args);};w.Intercom=i;var l=function(){var s=d.createElement('script');s.type='text/javascript';s.async=true;s.src='' + APP_ID;var x=d.getElementsByTagName('script')[0];x.parentNode.insertBefore(s, x);};if(document.readyState==='complete'){l();}else if(w.attachEvent){w.attachEvent('onload',l);}else{w.addEventListener('load',l,false);}}})();


We hope you all find the tag useful, there are certainly a few more features we would like to include in a future update, including but not limited to:

  • Direct Google Analytics integration for events – pushing the events directly into a provided UA-ID so that you have clear visibility of your custom Intercom interactions.
  • Advanced Custom dataLayer naming conventions – essentially letting you call the dataLayer events whatever you want directly from the tag.

So please, let us know your thoughts, what you would like to see in the future and any bugs so we can help make integrating with Intercom through GTM easier for you during these turbulent times.