Let's cut to the chase. You want to get building – we want to help you. In this guide, we'll run through exactly how you can:
- Create a new developer workspace to build and test all your apps
- Create a new app to get building
- Make your first API call
- Setup an example app using our Messenger Framework
You'll need to set up an Intercom account in order to get started, and get an app with the authorization you'll need. You can either use your existing account, or create a new development workspace.
Sign in/up via SSO, or fill in your existing/new details.
Developer Workspace Limitations
These free workspaces we provide you will not have all the functionalities of a standard Intercom production workspace. These limitations include:
- No outbound emailing.
- Draft Articles that can never be set live.
- A watermarked Messenger, showing that it's linked to a Developer Workspace.
- A maximum of 20 users/leads (if you have more than 20 users/leads, the oldest extras will be archived automatically on a regular basis).
Now that you have your workspace, it's time to create your first app.
Everything is an app
Anytime you want to interact with the Intercom Platform–via the REST API, webhooks, or to build an app for the Messenger–you start by creating an app. Apps are like containers for the various functionality that you have access to on the Intercom Platform and each app can be managed and installed to your other Intercom workspaces independently.
Simply, click New app. You'll see a modal box, where you should name your app (you can always change this later), and select the workspace you want to install it on.
Once you're ready, click Create app. This will create the app and pre-install the app to your selected workspace. On Your Workspaces page you can manage where your app is installed, and view your Access Token for each workspace.
You can also view your Access Token on the Authentication page, which provides greater details alongside OAuth settings.
Access Tokens or OAuth
An Access Token is used to access your own workspace data via the API. You should never give your Access Token to a 3rd party. If you're building an app that's destined to be used only by your own teams in your own workspaces then using your Access Token is generally sufficient.
However, if you plan to make your app publicly available on the Intercom App Store you'll need to set up OAuth. But don't worry, you can always decide to set up OAuth at a later date. For more information on authorization and setting up OAuth take a look at the guide here.
Now that you have a workspace and an app, you can use your Access Token to make your first call to the REST API. Here's a little sample code that you can run in your terminal to make a call and list all the users in your developer workspace (which probably won't return any users at this stage):
# Copy the cURL request below into your Terminal. # Replace **<INSERT_ACCESS_TOKEN_HERE>** with your Access Token from Step 3. # Run the query to see a response with all your users listed. $ curl https://api.intercom.io/users \ -H 'Authorization:Bearer <INSERT_ACCESS_TOKEN_HERE>' \ -H 'Accept: application/json'
In order to get started quickly with our Messenger Framework, we've created a sample Node.js app that you can setup to test in a few simple steps.
Go to our Glitch project through this link, and click the Remix This button like so:
You will now see the name of your new project in the top left like so:
Your app's now created, so you'll need to provide us with the webhook URLs. These are where Intercom will send the POST requests to. Replace
<PROJECT_NAME> with your own Glitch project name in the URLs below, and insert them into the correct sections in your Messenger Framework section (found in the Developer Hub).
Submit: https://<PROJECT_NAME>.glitch.me/submit Configure: https://<PROJECT_NAME>.glitch.me/configure Initialize: https://<PROJECT_NAME>.glitch.me/initialize Submit sheet: https://<PROJECT_NAME>.glitch.me/submit-sheet
An example is shown like so with our Glitch project name:
Make sure to also tick every one of the Capabilities. This will ensure it works everywhere you can insert Apps in the Messenger.
Your app is now installed and ready to go - try it out!
Add the app in a conversation or to your Messenger Home and play around to see it in action. You can also see how it should look on the
README.md file in the Glitch project.
Remember that this is an example app to show off the UX, with no integration to your backend present.
You will need to configure our app in order to integrate it with your own app (or with our API). Navigate to the
server.js file in the Glitch project to add/edit any one of the request flows, and make sure to understand the objects/components you'll need to know.
🎉 Congratulations - You created a workspace, built an app, and made a call to our API!