App guidelines

We want customers to be confident that any app they connect to their Intercom account will be useful, work well and use their data responsibly.

We've put together the following guidelines to help you build a successful app. Please take a few minutes to read them before getting started and ensure that any app you intend to make publicly-available complies.

Following these guidelines will improve your chances of being approved for OAuth.

These guidelines are in addition to our Terms of service, Privacy Policy and our general Developer Guidelines.

Use Intercom conventions

Intercom is a system with many components which work together. Messages, conversations, users, notes, tags, custom attributes, and many more. Before you get started you should understand what customer problems you’re solving and which of these Intercom components you’re going to use.

It is also important to use these components according to the conventions of the Intercom products and of other 3rd party integrations. Using Intercom concepts in bespoke ways confuses your customers and makes your app less useful.

The best way to get familiar with these conventions is to use Intercom. You can also learn more in these resources:

Build something that adds value

An ecosystem of unique, useful apps and integrations benefits us all – you, us and our customers.

If you’re an Intercom customer it can help to get started building an app for your own team – many developers start by building tools to solve their own problems, then share them with the world. It’s a great way to understand what your customers will want from your app.

If you’ve never used Intercom we’d recommend you create a free account and try it out. If you have any question along the way, just let us know.

Top tips:

Ensure your app is complementary to one or more of our products
Try and build something unique – take a look at other apps that exist and make sure your idea is different or better than what already exists
Don’t rebuild Intercom - your app should add new and unique capabilities that are useful to users

Use our APIs and tools effectively

You should build your app so that it works well and is reliable. If you ever have questions – for example, when to use the Bulk API – we'll be happy to help.

Top tips:

Use OAuth as the only method of authorization for your app and use the scopes you've been granted for the use case(s) they were granted for
Use a supported (ideally the newest) API version to build your app
Use our APIs as intended and as efficiently as possible - e.g. use Bulk APIs where possible, use continuous syncing over bulk exports etc.

Help customers understand your integration and provide quality support

For some customers, sharing Intercom data with a third party can be a slightly scary experience. You should make the value your app clear, as well as what you will (and won’t) be using their data for.

Top tips:

Only ask for the OAuth scopes you need. Clearly let your customers know why each scope is important. It is good to map app features to scopes so customers understand why you need each one – this also makes your application for OAuth more likely to be approved by us
Provide customers support through Intercom and/or Twitter, Facebook, email or phone
Describe your app accurately and don’t deliberately mislead or confuse customers – provide clear text, screenshots, and videos to make the value of your app clear.
Use Intercom branding in accordance with our guidelines and do not imply approval or partnership with Intercom unless you have our written consent to do so
It's fine to promote your app, but please don't send unsolicited spam to Intercom customers

Make it easy to set up

Making it easy to set up your app makes it more likely that a customer will use it, and can also help you attract new customers.

When a customer clicks “Connect with Intercom” from within your product or landing page, you should immediately authenticate using Intercom OAuth before any other steps occur.

If an account with your product is required it should automatically be created by fetching the credentials from Intercom (via our /me endpoint). If you absolutely need to ask customers to manually sign up, you should pre-fill as much customer information as possible (for example their name, company, and email).