Configuring your app

Now you have an understanding of how Apps in the Messenger work, you'll need to provide the necessary details in your Messenger Framework page in the Developer Hub to start building your app.

Specifying your app's capabilities

You'll first need to to specify where your app will work in Intercom:

You can select a combination of the three. The selection boxes look like so:

If a particular location is not selected, your app will not appear when you go to add the app in that location.

Providing Request Flow URLs

You'll need to provide the URLs where we'll send the relevant POST requests to. These are as follows:

Request URL name
Required?
Description

Initialize

Required

The URL where we’ll POST all initialize-card requests sent by the framework. More on the initialize flow through this link.

Configure

Optional

The URL where we'll POST all configure-card requests sent by the framework. If your app doesn't require any information from teammates when it’s being added then please leave this blank. More on the configure flow through this link.

Submit

Required

The URL where we'll POST all submit-card requests sent by the framework. More on the submit flow through this link.

Sheets

Optional

The URL where we'll POST all submit_sheet requests sent by the framework. More on the sheets flow through this link.

You can always change the values you enter above at a later date. The input boxes look like so:

Providing Installation URLs

This step is only necessary if you plan to publish your app to the Intercom App Store

Setting up OAuth

Apps in the Messenger must implement OAuth when they are to be publicly listed, and have to be installed via the Intercom App Store. To achieve this, you'll first need to set up the standard OAuth authentication flow.

Then, you'll need to provide the following URLs on your App store listing page. Under Installation, select Directly via Intercom app store to bring up the input boxes to insert your URLs:

URL Name
Required?
Description

Install

Required

The URL pointing to your external website/app, kicking off the OAuth 2.0 flow for installing your app via the App Store. More on Setting up OAuth, and what this URL should look like, through this link.

Uninstall

Optional

If you supply an uninstall URL we'll send a POST request to this URL when a teammate uninstalls your App via the App Store. You can use this to handle any cleanup or de-authorization you need to.

Authenticate with your Product

Once you've gone through the OAuth flow to receive a code from Intercom (which you can swap for an Access Token), you can optionally have the user authenticate with your product. Effectively, this links Intercom and the end users account with your own product.

Order of Authentication

You must have the user authenticate through the Intercom OAuth flow before you prompt them to authenticate with your own app. This is for security measures and to ensure a clean process on your side, whereby you can rest assured that they have approved access to their data and have installed with Intercom successfully.

Redirect back to the App Store

The final step is to send the user who is installing your app back to the Intercom App Store. You must redirect back to the App Store at the end in order to post back if the flow was successful or not:

If OAuth was successful

If Intercom OAuth and (optionally) OAuth to your product are both successful you should redirect the user to https://app.intercom.io/appstore/redirect?install_success=true.

This URL will bring them back to the App Store and will display a success message.

If OAuth was unsuccessful

If either Intercom or your product's OAuth was unsuccessful you should redirect the user to https://app.intercom.io/appstore/redirect?error_message=<your error message>

You can fill in the error message parameter with any error information you have.


What's Next

Understand how to setup OAuth properly, and then see our guidelines for building apps in the Messenger. It's a foolproof way to ensure your app gets listed on the Intercom App Store.

Setting up OAuth
Apps in Messenger: Best Practices

Configuring your app


Suggested Edits are limited on API Reference Pages

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