Home
/
Set up a Workspace

Set up a Workspace

Build context-relevant, action-oriented apps directly on top of Intercom - whether you're publicly integrating your service with ours, or you're building for your own team's private usage.

Step 1: Create an Intercom workspace

You'll need to set up an Intercom account in order to get started. If you have your own workspace already and want to use that for development, then login through the usual page here.

We highly recommend that you create a new developer workspace for developing apps. Developer workspaces are totally free and intended for development purposes only.

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 or push notifications.
  • Help Center Sites 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).
  • Developer Workspaces cannot be converted into production workspaces.

Step 2: Create an app

Now that you have your workspace, it's time to create your first app in the Developer Hub.

Everything is an app

Anytime you want to interact with the Intercom Platform via our REST API, webhooks, or to build an app for the Messenger, you start by creating an app. Think of apps as containers for various pieces of functionality that you have access to on the Intercom Platform and each app can be managed and installed to your other Intercom workspaces independently.

  1. In Your Apps, click New App: A screenshot of the Intercom Developer Hub, with the "Create new app" button highlighted
  2. In the modal box, put the name of your app and select the workspace you want to install it on: A screenshot of the app creation modal
  3. Click Create app. This will create the app and pre-install it to your selected workspace.
  4. You can view your Access Token on the Authentication page, which provides greater details alongside OAuth settings: A screenshot of the Authentication page, with the Access Token highlighted

You can also manage which workspace your app is installed on within the Your Workspaces page and gain Access Token's for each of these workspaces.

Access Tokens or OAuth

An Access Token is used to access your own app 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 apps then using your Access Token is generally sufficient.

If you plan to make your app publicly available on the Intercom App Store, you'll need to set up OAuth. 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.

Step 3: Make your first API Call

For your first API call, we're going to create a new Contact in Intercom. You can do this by making a POST request to https://api.intercom.io/contacts.

Copy the snippet below into your terminal, making sure to swap YOUR_ACCESS_TOKEN for the access token of your app from Step 2.

curl --request POST \
     --url https://api.intercom.io/contacts \
     --header 'accept: application/json' \
     --header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
     --header 'content-type: application/json' \
     --data '
{
  "email": "jdoe@example.com"
}
'

Step 4: Learn more

This was just the beginning. Here are some ideas of what you might do next: