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 setup a simple app. We are using a tool called Glitch to build an app with this code. Glitch is a platform that lets you create, test and update apps, for free, with publicly available URLs.

The only prerequisite required is that you already have an Intercom workspace. If not, go here and follow the steps to create one.

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"} },
        ],
      },
    },
  });
});

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 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:
2. Copy both the Initialize URL and Submit URL.
3. 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.
4. Make sure Add to conversation details in this section is also checked.
5. Click Save and you're ready to go!

Step 4: Create a conversation

In order to add the app in the Inbox, we need to have an active conversation in our workspace. The easiest way to achieve this is to start a new conversation via Intercom Messenger. To do this, you need to install Messenger in your Glitch app.

1. Copy this code:

<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>

2. Paste the code into the views/index.html file in your Glitch project, where it says # INSERT YOUR MESSENGER CODE HERE:
3. Replace the WS_ID with your own workspace ID. You can grab it from the URL in Intercom.
4. 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.

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.

Step 6: Add some functionality with an action

You might have seen that for now the app does not do much: if you click the "Click me" button, nothing happens. For some apps, you may not need to take any action (i.e. 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 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" },
        ],
      },
    },
  });
});

Take a look at the components in our reference to see what you can build as the content of your app within the canvas object. You might find this guide helpful too.