Build an app for your Inbox

Before you get started

In this quickstart tutorial we'll be using Canvas Kit to build an interactive app for use in the conversation details in your Inbox.

We have provided some Node.js code that you can use to quickly setup a simple app. Plus, we are using a tool called Glitch to build an app with this code.

Glitch is a platform that let's you create, test and update apps, for free, with publicly available URLs. If you are interested you can find more info on Glitch here.

The only prerequisite required is that you already have an Intercom workspace. If you don't have one yet then quickly go here and follow the steps to create one.

Why Node.js?

You can use whatever language you like when creating Intercom apps. We chose Node here just as an example of a common language which most people may be familiar with.

Step 1: Copy and paste some code

Create your Glitch Project by clicking on the Remix button below.

Copy the sample code as shown into the server.js file on the left hand side of your Glitch project.

const express = require('express');
const bodyParser = require('body-parser');
const app = express();

app.use(bodyParser.urlencoded({ extended: true }));
app.use(bodyParser.json());
app.use(express.static(__dirname));

// http://expressjs.com/en/starter/static-files.html
app.use(express.static('public'));

// http://expressjs.com/en/starter/basic-routing.html
app.get('/', function(request, response) {
  response.sendFile(__dirname + '/views/index.html');
});
        
const listener = app.listen(process.env.PORT, () => {
  console.log('Your app is listening on port ' + listener.address().port);
});

/* 
  This is an endpoint that Intercom will POST HTTP request when the card needs to be initialized.
  This can happen when your teammate inserts the app into the inbox, or a new conversation is viewed.
*/

app.post("/initialize", (request, response) => {  
  const body = request.body;  
  response.send({
    canvas: {
      content: {
        components: [
          { type: "button", label: "Click Me!", style: "primary", id: "url_button", action: {type: "submit"} },
        ], 
      },
    },
  });
});

Don't expect anything to happen after pasting this in - you'll need to follow the rest before you see a functional app in the Inbox.

Step 2: Create an app

You now need to associate that code to your own Intercom workspace.

To do this, you must create an app. Don’t worry - this will be totally private to you and your workspace.

Click the “New App” button in the Your Apps section within the Developer Hub, give your app a name, and select your workspace.

Step 3: Give your app some URLs

Next, we need to tell Intercom where to send requests when someone uses your app.

For now let's just focus on the initial request. This will be sent when a teammate adds it to their inbox sidebar, or when a new conversation is viewed. When either occurs, Intercom will send you a request for information about your app. You just need to tell Intercom where to send this request.

  1. Glitch already provides us with an easy way to get public URLs - simply click on the Show Live button to see these:
  1. Copy both the Initialize URL and Submit URL.

  2. Paste them into the relevant fields (Initialize flow webhook URL and Submit flow webhook URL) in the Configure > Canvas Kit > For teammates page of your app in the Developer Hub.

  3. Make sure Add to conversation details in this section is also checked.

  4. Click Save and you're ready to go!

Step 4: Create a conversation

In order to add the app in the Inbox, we actually have to have a conversation in our workspace. The best way to get one is to send one in via the Messenger, plus it's always useful to have the Messenger for testing purposes all the same.

  1. Copy the code below:
<script>
  var WS_ID = "YOUR WORKSPACE ID";

 window.intercomSettings = {
    app_id: WS_ID
  };
</script>

<script>(function(){var w=window;var ic=w.Intercom;if(typeof ic==="function"){ic('reattach_activator');ic('update',intercomSettings);}else{var d=document;var i=function(){i.c(arguments)};i.q=[];i.c=function(args){i.q.push(args)};w.Intercom=i;function l(){var s=d.createElement('script');s.type='text/javascript';s.async=true;s.src='https://widget.intercom.io/widget/APP_ID';var x=d.getElementsByTagName('script')[0];x.parentNode.insertBefore(s,x);}if(w.attachEvent){w.attachEvent('onload',l);}else{w.addEventListener('load',l,false);}}})() </script>
  1. Paste it into the views/index.html file in your Glitch project, where it says # INSERT YOUR MESSENGER CODE HERE.
  1. Change the WS_ID to your own workspace ID.

  2. You should see your Messenger pop up in the Show Live page. Click on the Messenger and start a New conversation - once it's sent, you will have a conversation in your Inbox.

Having issues?

Issues usually stem from having the incorrect, or no, workspace_id - make sure to follow Step 3 and replace the text "YOUR WORKSPACE ID" with your own workspace_id. You can grab this from the URL in Intercom.

Step 5: Add your app to the Inbox

The code in Glitch has setup your endpoints, which you've now added to Intercom in order to specify where we send the requests to. We've also created a conversation meaning we can now use your Inbox app. Let's go see how it looks!

  1. Click on the link to the workspace associated with your app in the Your apps section.

  2. Go to the Inbox by either clicking on the Inbox icon in the left hand panel or following that link.

  3. Select Edit within the side panel (on the top right hand side) and then + Add Card to bring up a list of apps whereby you should be able to choose yours. You may have to scroll down as these will be listed alphabetically.

Problems adding your app to the Inbox?

If you can see your app but you get an error when trying to add it then your URLs may be incorrect. Double check that these are correct.

Step 7: Add some functionality with an action

You might have seen that for now the app does not do much - if you click it, nothing happens. For some apps, you may not need to take any actions (ie. you just want information to show and for the data to update). However, for this app, we'd like the button to take a Submit action and show a new screen.

To do this, copy the code below and just append it to the code already in your Glitch server.js file.

It will add a submit endpoint (which you already added the URL for earlier). An action has already been defined so that if the button is clicked, the submit endpoint will respond with a new component.

app.post("/submit", (request, response) => {  
  const body = request.body;  
  response.send({
    canvas: {
      content: {
        components: [
          { type: "text", text: "Someone just clicked something -> You just responded with a text component which you're now showing here", 
           style: "header", align: "center" },
        ], 
      },
    },
  });
});

Go take a look at the components in our reference and see what you can build as the content of your app within the canvas object. There's more definitions on these concepts there too.



Build an app for your Inbox


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.