Build an app

Last updated 7 October 2026

An app is software, run by you, that works with other companies’ Intercom Chat workspaces. A workspace administrator installs it, approves what it may do, and chooses the channels it can use. It then posts and reads through a small API, with a token that works for that one workspace and nothing else. Approved apps can be listed in the public marketplace.

For your own tools posting into one channel, you do not need this: use an app under Admin, then Apps, which gives you a secret web address. See the developer overview.

What an installed app can and cannot do

• It posts under its own name. It is never a person and has no author.
• It sees only the channels the administrator gave it. Direct messages are never available to apps.
• It can never see anyone’s email address.
• Its token works for one workspace. It cannot reach any other.
• What it posts is checked by the workspace’s data-protection rules like any message.

1. Register your app

1. Sign in to any Intercom Chat workspace you own or administer (a free one is fine) and open Admin, then Developer.
2. Fill in the details and choose the most your app may ask for. Ask for as little as you need.
3. Give at least one redirect address. It must start with https:// (or http://localhost for testing) and is matched exactly.
4. Copy your client secret when it is shown. It is shown once; we keep only a fingerprint. Keep it on your server, never in a web page or a phone app.

A new app is a draft: only your own workspace can install it, which is how you test it.

Permissions (scopes)

2. Send the administrator to approve it

Send the person’s browser to their workspace, using the address they give you (for example acme for acme.intercomchat.com):

https://WORKSPACE.intercomchat.com/apps/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fyourapp.example.com%2Fcallback
  &response_type=code
  &scope=channels%3Aread%20messages%3Awrite
  &state=A_RANDOM_VALUE_YOU_CHECK_LATER
  &code_challenge=...&code_challenge_method=S256

• redirect_uri must be exactly one of the addresses you registered. If it is not, the page says so and nothing is sent anywhere.
• scope is optional (space-separated). It must be within what you registered. Leave it out to ask for everything you registered.
• state is optional but you should use it: make it unguessable, remember it, and check it comes back unchanged.
• PKCE is optional but recommended. Use code_challenge_method=S256 and make the challenge the base64url SHA-256 of a random verifier you keep. If you send a challenge you must send the verifier in step 3.

The administrator sees who you are and what you ask for, picks the channels, and approves. Their browser is then sent to your redirect address with code and your state. If they cancel, it is sent with error=access_denied.

3. Swap the code for a token

From your server, within 5 minutes. A code works once.

curl -X POST https://intercomchat.com/api/oauth/token \
  -d grant_type=authorization_code \
  -d code=THE_CODE \
  -d redirect_uri=https://yourapp.example.com/callback \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d code_verifier=YOUR_PKCE_VERIFIER

You get:

{
  "access_token": "icat_…",
  "token_type": "bearer",
  "scope": "channels:read messages:write",
  "workspace": { "id": "…", "subdomain": "acme" }
}

Store the token like a password. Installing the app again in the same workspace replaces its token. Using a code a second time revokes what the first use created. You may also send the client id and secret as HTTP Basic credentials instead of in the body.

4. Use the API

Send Authorization: Bearer icat_… to https://intercomchat.com/api/app/v1. Everything is JSON.

curl -X POST https://intercomchat.com/api/app/v1/channels/CHANNEL_ID/messages \
  -H "Authorization: Bearer icat_…" -H "Content-Type: application/json" \
  -d '{ "text": "Deploy finished" }'

Errors and limits

• Errors look like { "error": { "code": "not_found", "message": "…" } }.
• 401 invalid_token: the token is wrong, was revoked, or the app was suspended.
• 403 insufficient_scope: the administrator did not approve that permission.
• 404 not_found: the channel does not exist or was not given to your app. You cannot tell which, by design.
• 422: the workspace’s data-protection rules refused the message.
• 429 rate_limited: 300 requests a minute per installation. The token endpoint allows 30 a minute per address and 60 per app.

An administrator can change an app’s channels, or remove it, at any time. Removing it makes its token stop working at once. Your app should expect this and handle 401 by treating that workspace as uninstalled.

Getting listed in the marketplace

When your app works, choose Submit for review on its page. You need a summary, a description, your name as shown publicly, a website, a support email and a privacy policy address. We look at what the app asks for against what it says it does. Apps are approved when:

• they ask only for the permissions they genuinely need;
• the description is honest about what happens to the information the app sees;
• the privacy policy exists, is yours, and says what you do with workspace data;
• the support address is monitored;
• they do not send unwanted bulk messages, scrape, or try to get around any limit.

Changing an approved app’s redirect addresses or permissions sends it back for review (other edits do not). We may suspend an app that breaks these rules; installed copies then stop working until it is restored. Installed apps from other developers are theirs, not ours: their own terms and privacy policy apply.

Questions

support@intercomchat.com.

Xypno Business Solutions Ltd. Questions? Email support@intercomchat.com.