Building Successful Apps

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.

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 objects you're going to use.

It is also important to use these objects 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 objects and patterns is to use Intercom. You can also learn more in these resources:

• Events vs Custom Attributes
• Intercom glossary

Build something that adds value

An ecosystem of unique, useful apps and integrations benefits us all - you, us and all Intercom customers.

If you're an Intercom customer it can help to start 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 questions along the way, just let us know.

• 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 we're always happy to help.

• 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 of your app clear, as well as what you will (and won't) be using their data for.

• 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 setup

Making it easy to set up your app means more customers are likely to use it, and it can help you attract new customers.

• The easiest way to allow customers to install your app is to publish your app in the Intercom App Store
• If you're going to use a "Connect with Intercom" button in your own product, ensure that clicking that button immediately takes the customer to 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)

Third party guidelines can be affected by apps

Intercom is used upon multiple platforms, and thus the policies of browsers and OS's must be taken into consideration when building apps. If we take our iOS SDK as an example, Apple specifies in its App Store guidelines that in order to pass the review to be listed, you cannot promote or cater for in-app purchases away from Apple. Therefore, all apps that utilize Canvas Kit in conversations or Messenger Home must ensure that there is no mention or provision to access external mechanisms for purchases or subscriptions.