These are answers to frequently asked questions related to:

You can create a new developer workspace for developing apps. Developer workspaces are free and intended for development purposes only. Once you've created the new workspace you can follow this guide to create an app and make your first API call.

You can create a new app for your production workspace and get the access token for the app by going to https://app.intercom.com/a/apps/{your-workspace-id}/developer-hub/

When you turn on your Articles Help Center, your content is available through intercom.help by default. Your URL will look like this: intercom.help/exampleapp.

If you’d like to use a different URL, you can create one by manually setting up a custom domain. This will involve entering the custom domain in your Help Center settings, creating a custom CNAME record, and optionally configuring SSL. Find the full instructions for set up in our developer documentation.

SSL (or TLS), is the most widely used way to secure the connection between your server and your browser. It ensures the connection between the server and browser is encrypted and safe, and appears as HTTPS.

There are two ways to set up SSL with Articles on your custom domain:

You can configure SSL for your custom domain to keep sensitive information encrypted. If you want to do this, make sure you’ve set up your CNAME with a DNS provider that supports SSL, like Cloudflare.

Follow the guide in our developer documentation for setting up SSL. Note that depending on the provider you have chosen set up steps may vary.

The current version of the API is 2.11. You can find the documentation for the API on our developer documentation site. You can also change the version that your app is using in your Developer Hub by following the steps listed in this guide.

If you are using the Intercom API, you can also change the version within the HTTP header of your request.

The following endpoints are available in version 2.11 of the Intercom API:

Yes, if you'd like to trigger an article in the Messenger, you can use the showArticle method from the JavaScript API. The article will open within the Messenger and clicking the Messenger back button will return to the previous context. If the Messenger is closed when the method is called, it will be opened first and then the article will be shown. This is available across all platforms in the Messenger.

In Intercom users fall under the label of contacts. There is no endpoint for bulk creating contacts using the API but you can use the create contacts endpoint to create a script that imports users or follow this tutorial which will give you the code samples to get started.

Be sure to set up a rate limiting check to make sure you are not hitting the limit, which is currently 10,000 API calls per minute for each app and 25,000 API calls per minute per workspace.

To retrieve an archived contact's data you first need to unarchive the contact, which you can do with the unarchive contact API endpoint if you have the contact's ID.

Then you will be able to regain access to the contacts data through the get a contact API endpoint and their conversations through the retrieve a conversation API endpoint.

If you would like to assign a conversation to a team using the API you have two options.

The first option is to assign a conversation directly to an admin or a team using the manage a conversation API endpoint. You need to have access to the Intercom provisioned id for the conversation as well as the admin_id and the assignee_id.

The other option is to run assignment rules that you have already set up on the conversation using the run assignment rules on a conversation API endpoint. You need to have access to the Intercom provisioned id for the conversation.

You can test out the functionality from the "Try It" feature in our developer documentation, the Intercom Postman collection, or in your own terminal or IDE. Don't forget to use your Intercom access token as a bearer token.

A note in an internal comment only visible to teammates. To add a note to a conversation you can use the reply to a conversation API endpoint. You will need to choose a messsage_type of note and a type of "admin" along with the admin_id that the note should come from.

You can test out the functionality from the "Try It" feature in our developer documentation, the Intercom Postman collection, or in your own terminal or IDE. Don't forget to use your Intercom access token as a bearer token.

If you have already created a tag in the UI, you can use that tag to apply to conversations. You can also create a new tag using the API.

To use the add tag to a conversation API endpoint, you will need to have access to the conversation_id of the conversation to tag, the Intercom provisioned id of the tag and the admin_id.

You can test out the functionality from the "Try It" feature in our developer documentation, the Intercom Postman collection, or in your own terminal or IDE. Don't forget to use your Intercom access token as a bearer token.

You can create a conversation from the API that has been initiated by a contact (ie. user or lead) by using the create a conversation API endpoint. The conversation can be an in-app message only.

You will also need the Intercom provisioned id for the contact and the body text. Use to start the conversation.

You can test out the functionality from the "Try It" feature in our developer documentation, the Intercom Postman collection, or in your own terminal or IDE. Don't forget to use your Intercom access token as a bearer token.

To close a conversation using the API you can use the manage a conversation API endpoint. You will need to have the Intercom provisioned id of the conversation, your admin_id and use a message_type of "close".

If you need to redact only a certain part of the conversation, use the redact a conversation part API endpoint.

You can test out the functionality from the "Try It" feature in our developer documentation, the Intercom Postman collection, or in your own terminal or IDE. Don't forget to use your Intercom access token as a bearer token.

To set up a custom notification when an action is taken, such as a teammate being assigned to a conversation, you can use webhooks.

You will want to use the conversation.admin.assigned conversation topic. You can find all of the conversation topics in our developer documentation.

You can then subscribe to this webhook topic in the developer hub by following the steps in this guide. You'll also need to have a publicly accessible endpoint URL available for the action to take once the webhook is hit to deliver the notification to your channel of choice.

To create a ticket using the Intercom API, you will first need to create or obtain the type of ticket to label the new ticket. Then you can create the ticket using a curl request or with a programming language of your choice.

Follow this guide from our developer documentation to create a ticket type and create a new ticket.

If you are using the API to retrieve tickets and ticket data, you can use the search tickets API endpoint. To exclude back office ticket types, set the field to ticket_type_id and use the != operator to exclude the ticket_type_id assigned to back office ticket types.

If you are using the API to retrieve a conversation or list conversations with back office tickets associated with the conversations and you'd like to exclude them, you can similarly filter out any results that have the back office ticket type as an attribute. Linked tickets can be found at the tickets parameter in the response or under linked_objects.

One other option available is to use the API to tag conversations with a back office ticket associated with them. You can then use the tag in order to filter by ticket category.

If you are getting a 403 API Plan restricted message in a response this means that the API you are trying to use is not available on your app's plan.

In order to access the API you'll need to upgrade your plan. You can find out more about Intercom plans on this page. You can find a full list of error codes and HTTP responses in our developer documentation.

If you are getting a 409 conflict message in a response this means there is existing data in your Intercom workspace that clashes with the request data. This can occur if you try to create a contact and there is a contact with that email address already added within your app.

To avoid this error you can use the update endpoint instead or create a new contact by user_id. You can find a full list of error codes and HTTP responses in our developer documentation.

If you are getting a 429 message it means the client has reached or exceeded a rate limit, or the server is overloaded. Each app has a default rate limit of 10,000 API calls per minute for each app and 25,000 API calls per minute per workspace. More information on rate limits is available in our developer documentation.

To avoid this error you can set up a rate limiting check to make sure you are not hitting the limit. You can find a full list of error codes and HTTP responses in our developer documentation.

Private apps have a default rate limit of 10,000 API calls per minute per app and 25,000 API calls per minute per workspace. This means that if a workspace has multiple private apps installed, every one contributes towards total number of requests.

Public apps have a default rate limit of 10,000 API calls per minute for each app and 25,000 API calls per minute per workspace. This means that if a workspace has multiple public apps installed, each one has its own separate request limit without contributing to the others. More information on rate limits is available in our developer documentation.

If you are creating your own reports using the API you may notice that there are some differences between the two reports. This can happen for a few reasons.

One common issue is when dates and times do not match. This is often because the time zone that you are using in your Intercom workspace is different than the time zone you are using to query the API. To fix this, either adjust your API query parameters to match your workspace time zone, or change the time zone of your custom report.

Another issue is that you may be using metrics that do not align with the Intercom reporting UI metrics. There are some metrics available in the reporting UI that are not available via the API because they are calculated metrics. Some of those can be created by using the API and performing the calculations on your end. Check out the guide for building your own reports from the Intercom developer documentation.

If you are looking at the conversations reports available in the UI versus reports pulled using the conversations API, you may notice that there is a difference in the number of conversations. This is because back office tickets associated with a conversation will be included when it is pulled from the API.

To solve for this, you can filter results after retrieving them via the list conversations, retrieve a conversation, or search for conversations API, and separate the tickets from conversations using the ticket field in the conversation API response. The ticket field will be populated with an object if it is a ticket and will be null if it is a conversation.

Webhooks allow you to subscribe to real-time notifications of events happening in Intercom, like when a contact is created or an incoming message is received.

You can see the webhooks available for each version in our developer documentation. Once you've identified which webhook you need follow this guide to set them up.

There are no plans to add new webhooks on our roadmap, but if there is a webhook your team needs, please submit a request to the team or add it to the product wishlist in the Intercom community.

Intercom APIs for listing and searching resources offer cursor-based pagination. This is available so that when you are requesting a large amount of data — like many conversations with all of their parts — you can receive and process them in smaller chunks.

For examples on how to use pagination with both the Intercom list APIs, which accept path parameters, and search APIs, which use query parameters, see our pagination guide.

For cursor-based pagination, Intercom uses a pointer that will refer to a specific record based on the limit that you set by the number of pages that you specify per request.

When returned in an object, the pointer will look something like 'WzXXXXXXXXXXXXXX'.

You can then use the pointer from the response in order to make the subsequent request for the next batch of data.

The pagination formatting in the request differs slightly between list APIs and search APIs, but the responses work the same.

You can see examples of curl requests on our Pagination page, and tutorials on using list APIs, and search APIs.

Any apps that interact with third party workspace data and apps built with Canvas Kit require OAuth to be in place. You should never ask users for their access token and only use OAuth for interacting with their data.

See the documentation for instructions on setting up OAuth.

You'll need to set up OAuth if you're building an integration with Intercom that accesses other peoples' Intercom data. This includes public apps that you plan to list on the Intercom app store as well as apps and integrations you will ask users to install through your own website. Learn more about OAuth from our developer documentation.

If you are only accessing data within you own Intercom workspace you can use an access token.

If you're building a private app that only accesses data in your Intercom workspace, you can use your Intercom access token for authentication. Find your access token in your developer hub and learn more about authentication here.

You can use your Intercom access token if you're using the API to access data in your own Intercom workspace. Find your access token in your developer hub and learn more about authentication here.

You can build an app for your Intercom Inbox by using Canvas Kit, a toolkit that allows you to build apps that work from directly within the Intercom UI.

Follow this tutorial to learn how to build your first Inbox app. You can also learn more about Canvas Kit and find reference docs in our developer documentation.

You can build an app for your Intercom Messenger by using Canvas Kit, a toolkit that allows you to build apps that work from directly within the Intercom UI.

Note that customizations are limited to what is capable through Canvas Kit and must be created within the Messenger: it's not possible to recreate or re-skin the Messenger.

Follow this tutorial to learn how to build your first Inbox app. You can also learn more about Canvas Kit and find reference docs in our developer documentation.

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.

For third-party installation instructions, see our developer documentation.

When you are ready to publish your app, you can follow the steps in the developer hub. You can find a guide on how to publish your app in our developer documentation.

The Intercom SDK for iOS enables you to use the Intercom Messenger in your app, have conversations with your customers, send rich outbound messages, show your Help Center, and track events.

You can install Intercom for iOS using Cocoapods, Swift Package Manager, or manually. Read the details here. You can find Intercom for iOS on GitHub along with a sample app that you can use to play around with the SDK here.

The Intercom SDK for Android enables you to use the Intercom Messenger in your app, have conversations with your customers, send rich outbound messages, show your Help Center, and track events.

You can install Intercom for Android using Gradle or manually. Read the details here. You can find Intercom for Android on GitHub along with a sample app that you can use to play around with the SDK here.

The Intercom React Native wrapper allows you to use Intercom for iOS and Intercom for Android in your React Native apps. Follow the setup steps here.