Intercom

Intercom integration guide

Intercom is a business messenger used by over 30.000 organizations to provide live chat, bots, product tours, and more.

In Clarify we use Intercom to provide a better onboarding experience and to provide support to our users.

Intercom messenger exampleIntercom messenger example

Intercom messenger example

Intercom is a paid product but they do offer a free 14-day trial for you to try them out and complete this guide.

In this guide, we'll show you how to include Intercom conversation statistics in Clarify in a few easy steps!

Intercom statistics in ClarifyIntercom statistics in Clarify

Intercom statistics in Clarify

We focus on two metrics in this guide:

General
Message request e.g. initiated by the user by clicking "Send us a message" in the chat widget.

Automated
Message replies from automated campaigns like Series in Intercom.

Getting started

1. Create an Intercom app

You'll need to create a private app in Intercom to generate the credentials which we need later. You can find more information in the Intercom developer hub.

Once you have created an app you'll find your Access token in Configure -> Authentication on your app page.

2. Node-RED setup

If you are new to Node-RED or haven't checked out our Node-RED guides yet, we recommend that you check out Introduction to Node-RED before continuing.

3. Prepare Parameters

In this part we'll format and check the parameters we are going to send to the Intercom API to receive message statistics.

First, in the Node-RED dashboard drag the Inject, Function & Debug nodes to your flow and connect the nodes.

Prepare parameters flowPrepare parameters flow

Prepare parameters flow

Double-click on the Debug node and set the Output to complete msg object. Then double-click the Function node and name it something like "Prepare parameters".

📘

Tip

In Node-RED you can drag a "Debug"-node and connect it to nodes to display the output data from that node. In the screenshot above you could connect the "Debug"-node to the "Build Query"-node to preview the output before connecting it to the "google"-node.

Double-click on the Prepare parameters node and use a function code like the example below.

We use the NPM package Luxon in the code above to work with date formats. You'll need to install this package or use a different package to handle dates. You can also check out the Node-RED guide.

const DateTime = global.get('luxon').DateTime;

msg.headers = {};
msg.headers["Accept"] = "application/json";

var today = DateTime.now().toISODate();
var earlier = DateTime.now().minus({days: 30}).toISODate();

const toDate = DateTime.fromISO(today).toSeconds();
const fromDate = DateTime.fromISO(earlier).toSeconds();

const tags = ["automated","general"];

tags.forEach((tag)=> {
    
    if (tag == "automated") {
        msg.payload = {
            "query": {
                "operator": "AND",
                "value": [
                    {
                        "field": "created_at",
                        "operator": ">",
                        "value": fromDate
                    }, 
                    {
                        "field": "created_at",
                        "operator": "<",
                        "value": toDate
                    },
                    {
                        "field": "source.delivered_as",
                        "operator": "=",
                        "value": "automated"
                    }
                ]
            }
        }    
    } else if (tag == "general") {
        msg.payload = {
            "query": {
                "operator": "AND",
                "value": [
                    {
                        "field": "created_at",
                        "operator": ">",
                        "value": fromDate
                    }, 
                    {
                        "field": "created_at",
                        "operator": "<",
                        "value": toDate
                    },
                    {
                        "field": "source.delivered_as",
                        "operator": "!=",
                        "value": "automated"
                    }
                ]
            }
        }    
    }
   
    msg.tagName = tag;
    msg.tagDate = DateTime.fromISO(today);
    
    node.send(msg);
    
});

return null;

When you are ready you can click the blue button in front of the Inject node (as seen in the screenshot above) to test and see if the parameters look Ok.

You should receive two debug messages which look something like the JSON below.

{
   "_msgid":"c7682127.32ce4",
   "payload":{
      "query":{
         "operator":"AND",
         "value":[
            {
               "field":"created_at",
               "operator":">",
               "value":1617055200
            },
            {
               "field":"created_at",
               "operator":"<",
               "value":1619647200
            },
            {
               "field":"source.delivered_as",
               "operator":"=",
               "value":"automated"
            }
         ]
      }
   },
   "topic":"",
   "headers":{
      "Accept":"application/json"
   },
   "tagName":"automated",
   "tagDate":"2021-04-29T00:00:00.000+02:00"
}

4. Request setup

Now we are going to send the actual request with the parameters to Intercom.
Start by dragging a Delay and "http request" node to your Node-RED flow, connect the new nodes, and use a Debug node in the end.

Flow with new Delay and "http request" nodesFlow with new Delay and "http request" nodes

Flow with new Delay and "http request" nodes

We add a Delay node in front of our "http request" node to limit the number of requests we send to the API at the same time.

Double-click on the Delay node and use a limit of e.g. 10 seconds per message.

When you are ready, double-click on the "http request" node.

"http request" node setup"http request" node setup

"http request" node setup

We are going to use:

  • Method POST
  • URL https://api.intercom.io/conversations/search to communicate with the Intercom API
  • Select Use Authentication and select the type bearer authentication from the dropdown.
  • In Token paste in the Access token from your app which you created earlier in this guide.
  • Return: Select a parsed JSON object

You can now test the actual workflow and check the response from the Intercom API by pressing the trigger button in front of the Inject node after you have deployed your workflow.

Your response will probably look similar to the JSON below. (We have removed parts of the data with personal information and other information to make it easier to read).

{
    "_msgid": "4a40cf63.eaeba",
    "payload": {
        "type": "conversation.list",
        "pages": {
            "type": "pages",
            "page": 1,
            "per_page": 150,
            "total_pages": 1
        },
        "total_count": 1,
        "conversations": [
            {
                "type": "conversation",
                "id": "999",
                "created_at": 1618840056,
                "updated_at": 1618840108,
                "waiting_since": null,
                "snoozed_until": null,
                "source": {
                    "type": "conversation",
                    "id": "790957236",
                    "delivered_as": "automated",
                }
            }
            ]
    },
    "topic": "",
    "tagName": "automated",
    "tagDate": "2021-04-29T00:00:00.000+02:00",
    "statusCode": 200,
    "responseUrl": "https://api.intercom.io/conversations/search",
    "redirectList": []
}

5. Prepare Data

Now we are going to prepare the data we receive from the API before we send it to Clarify.

Drag a Function node between the "http request" and Debug node as seen in the screenshot below.

Double-click on the Function node and name it "Prepare Result". In the Function use a code similar to the example code below.

const DateTime = global.get('luxon').DateTime;

if (msg.payload.total_count > 0) {
    var stats = {};
    
    for (var i = 0; i < 30; i++) {
      var statDate = DateTime.fromISO(msg.tagDate);
      var aDate = statDate.plus({ days: (i*-1) }).toISODate();
      stats[aDate] = 0;
    }
    
    var conversations = msg.payload.conversations;
    
    conversations.forEach((conversation)=>{
        var created = DateTime.fromSeconds(conversation.created_at).toISODate();
        stats[created] = stats[created] + 1;
    });
    
    let dates = [];
    let values = [];
    
    for (const [key, value] of Object.entries(stats)) {
      dates.push(DateTime.fromISO(key));
      values.push(parseInt(value));
    }
    msg.topic = "intercom-chat-" + msg.tagName.toLowerCase();
    msg.signal = {
        name: "Intercom Chat " + msg.tagName,
        labels: {
        "data-source": ["Intercom"],
      }
    };
    msg.payload = {
      "times": dates,
      "values": values,
    };
    
    node.send(msg);
}

return msg;

In the code above we check if the Intercom API returned any result. Then we create a map of empty dates for the period we want our statistics. We then loop through the result and increment the number of messages for that day. Finally, we format the timestamps and values before we send the message with this payload.

5. Send data to Clarify

In this step, we'll send the actual data to Clarify. As a preparation, you need to follow the guides Installing the Clarify nodes and Using the Clarify Insert node to make sure your workflow is able to correctly send data to Clarify.

When you have installed the Clarify nodes and setup credentials you can connect the Prepare Result node to the Clarify node. We also recommend that you connect two Debug nodes to the Clarify node. One for Errors and the other for other debug messages.

Final flow with the Prepare Result node connected to the Clarify insert nodeFinal flow with the Prepare Result node connected to the Clarify insert node

Final flow with the Prepare Result node connected to the Clarify insert node

To send the result to Clarify you can trigger the Inject node manually or set it up to trigger automatically as described below. We recommend you trigger it manually, to begin with, to verify that everything works as expected.

📘

Automatically trigger flow

The Inject node supports automatic triggering at certain intervalls. You can achieve this by double-clicking on the Inject node and configuring the Repeat setting. For example by setting "repeat interval" with "1 hour" the workflow above will trigger and update data every hour.

6. Visualize data in Clarify

When our workflow has run we now have 2 new signals in Clarify which contain data for Automated and General messages in Intercom.

To visualize the data we need to publish the signals as Items and create a new timeline.

If you follow this guide, you'll have Items similar to the ones below with fresh data.

Clarify with Intercom data ItemsClarify with Intercom data Items

Clarify with Intercom data Items

Drag the Intercom Items to the timeline and personalize the timeline with labels and colors that suit you and your company.

Clarify Timeline with Intercom dataClarify Timeline with Intercom data

Clarify Timeline with Intercom data

7. More data, please!

We recommend checking out the Intercom API reference for an overview of the API and to find new sources of information you can use.

Example
You can use the Contacts endpoint to send data about certain contacts that match a query. If you have an onboarding process or tag certain users you can show statistics about this in Clarify.
In such a case, you could re-use most of the examples in this guide and change the parameters and URL you use for the HTTP requests.

Congratulations!

You have now made your Intercom data more available and easier to explore. The next step in Clarify would be to invite your teammates to the timeline so that you can collaborate around this data.


Did this page help you?