Build an app for your Messenger

Before you get started

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

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 many people will 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 a conversation composer, Messenger home settings or User Message.
  Params sent from Intercom contains for example `card_creation` parameter that was formed by your `configure` response.
*/
app.post("/inbox/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.

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, given we're building an interactive app for the messenger, we need to tell Intercom where to send requests when someone uses your app. You can read more details about the lifecycle of Canvas Kit apps here but at a high level, Intercom will send you requests and you'll respond with the content that you want your app to show the end user.

Glitch already provides us with an easy way to get public URLs - simply click on the "Show Live" button to see these:

Copy both the Initialize URL and Submit URL, and paste them into the relevant fields (Initialize flow webhook URL and Submit flow webhook URL) in the Canvas Kit > For Users, Leads, and Visitors page of your app configuration settings in Intercom.

Don't click Save just yet - go to Step 4 first. Also, ensure that you only add the initialize and submit URLs. If you add other URLs for this tutorial you may encounter an error in later steps

Step 4: Specify how your app works

Before you save your update, you will need to specify how your app works. There are many ways to use your app, but for now, let's just focus on one capability and add it to your Messenger homescreen.

We need to tick the relevant option just above where you pasted the URLs in order to say where the app can be used within Intercom. Select Place on the Messenger home screen and click Save.

Step 5: Add your app to the Messenger

After clicking Save, you’ll be able to add the app to the Messenger.

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

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

  3. Select Add Messenger home apps and then Add an app to bring up a menu of apps whereby you should be able to choose yours. Note, if you have other apps installed you may need to scroll down to see your new app. It will be listed alphabetically.

Remember, this will appear on any site where your Messenger is installed. This should be fine unless you are using a production workspace that’s already being shown to your end users - in which case, it's best to use a free developer workspace which you can setup here

Problems adding your app to the homescreen?

If you cannot find your app then you may need to ensure that you have ticked the right capability. Alternatively, if you can see your app but you get an error when trying to add it then your URL may be incorrect so just double check that first.

Step 6: Check out your new app

You should now have some code in Glitch, which is linked to an app you created in Intercom via the URLs you copied to that app. Now we'll want to see how it looks in your Messenger.

If you already have a Messenger installed somewhere, then you can just check it there. Alternatively, install it on your Glitch project like so:

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>

Paste it into the views/index.html file in your Glitch project, where it says # INSERT YOUR MESSENGER CODE HERE.

Make sure to change the WS_ID to your own workspace ID - then, you should see your Messenger pop up in the "Show Live" page. Clicking on the Messenger should then show your app like so:

Having issues?

If you don't see anything, make sure to check that you clicked "Save" in Step 5 after adding the app.

Remember to also replace the text "YOUR WORKSPACE ID" with your own workspace ID. You can grab this from the URL in Intercom.

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. Our next steps will be to add some code and return a message when you click on the button.

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 an updated app.

app.post("/submit", (request, response) => {  
  const body = request.body;  
  response.send({
    canvas: {
      content: {
        components: [
          { type: "text", text: "Someone just clicked something AND you just created a new component!", 
           style: "header", align: "center" },
        ], 
      },
    },
  });
});

Once you have copied the code, go to your Messenger to interact with this.

You will notice that in our example, you can only click on the button once and then you will need to re-add your app to restart it. Don't worry - this is just a very simple example to get started. There are ways to refresh this automatically but for now we wanted to keep it as simple as possible.


What's Next

You can learn about the different requests/responses we've explained here in more depth with our Canvas Kit guide. Then, see more about the components you can use to build out the functionalities and visuals of your app more.

Canvas Kit
Canvas Kit Reference
Canvas Kit: Messenger Best Practices

Build an app for your Messenger


Suggested Edits are limited on API Reference Pages

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