Integration guidelines

We want customers to be confident that any integration 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 integration. Please take a few minutes to read them before getting started and ensure that any integration 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 integration 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 integrations benefits us all – you, us and our customers.

If you’re an Intercom customer it can help to get started building an integration 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 integration.

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 integration is complementary to one or more of our products
  • Try and build something unique – take a look at other integrations that exist and make sure your idea is different or better than what already exists
  • Don’t rebuild Intercom - your integration should add new and unique capabilities that are useful to users

Use our APIs and tools effectively

You should build your integration 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 integration 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 integration
  • 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 integration 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 integration 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 integration accurately and don’t deliberately mislead or confuse customers – provide clear text, screenshots, and videos to make the value of your integration 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 integration, but please don't send unsolicited spam to Intercom customers

Make it easy to set up

Making it easy to set up your integration 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).

Integration guidelines