Install your App
Your app will need to be installed on a workspace in order for it to be used there. Here you can learn how to:
Install your app on your own workspaces
You may want to install your app on a different workspace, either for testing purposes, or so you can use your app in the production workspaces that you own.
If you visit the Test & Publish > Your Workspaces page of your app in the Developer Hub then you should see all the workspaces you (as an Intercom teammate) are a member of.
You can click on Install app next to the workspace you want to install the given app on. This app will then be installed and an Access Token will be provided for that workspace so you can access its data through the API.
You can also then regenerate the Access Token (by clicking Regenerate token or uninstall this app which will revoke the Access Token (by clicking Uninstall app).
The app will no longer have access to data or be able to take actions on the workspace when uninstalled. Ensure uninstalling does not impact any workflows or teammates usage as it can be disruptive and is destructive. We give a warning box to ensure the action is deliberate before uninstallation and tell you where the app is currently being used if Canvas Kit capabilities are utilized.
Set up your app for third-party installation
If your app is going to be publicly used by others, then you'll need to do additional setup so they can install your app.
Installation URL
Third-parties (i.e. other Intercom workspaces) should always authenticate via OAuth. This flow will be kicked off via a URL hosted by yourself, which should then redirect to the Intercom OAuth URL. Our Setting up OAuth tutorial goes into depth on how you should setup the flow.
Once this flow is working, you need to decide where you want your app to be installed from:
Allow installation directly from your App Store Listing (recommended)
If your app uses any form of Canvas Kit capability, it's mandatory to allow your app to be installed through the listing on the App Store. This is because apps which use the Canvas Kit work from within Intercom by default, are often discovered through the product itself, and have onboarding built in to the listing to help people get started.
Your users are able to install your app directly from its listing within the Intercom App Store. This is strongly recommended because it drives higher install rates and reduces confusion on the part of teammates installing the app.
You need to select Directly from the Intercom App Store in the Installation section on the Test & Publish > App Store Listing page of your app in the Developer Hub. Insert the URL that kicks off the OAuth flow in the Direct installation URL field.
If installation was successful, you should redirect the user to <https://app.intercom.com/appstore/redirect?install_success=true>. This URL will bring them back to the App Store and will display a success message.
If installation was unsuccessful, you should redirect the user to <https://app.intercom.com/appstore/redirect?install_success=false&error_message=><your error message>. You can fill in the error_message parameter with any error information you feel is beneficial for the end user to know.
Allow installation from your own product or website only
Your app can also be installed through your own product or website exclusively. This means that you kick off the OAuth installation flow through your own product and redirect the user back there once complete.
Your listing will need to provide a Learn More URL - a page on your site where users can find out more detail about your app, and how to install and use it. This can be a landing page or a help doc. You can use UTM tags if you want to track referrals from your listing.
Uninstallation
If you want to be notified when someone uninstalls your app or revokes access through any means, then you can optionally provide a URL for us to send you a POST request to.
You can use this to handle any cleanup or de-authorization on your side. The JSON payload will be as follows:
{ "app_id": "abc123" }
You can also uninstall an app and revoke access either for yourself or on behalf of a customer by making a POST request to the https://api.intercom.io/auth/uninstall endpoint with the given Access Token you want to deauthorize.
$ curl https://api.intercom.io/auth/uninstall \ -X POST \ -H 'Authorization:Bearer <Access token>' \ -H 'Accept:application/json' -H 'Content-Type: application/json' -d