Getting 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 setup a simple app, but you can use whatever language you like. 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 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("/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 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.

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

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.

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:

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.