Use this article to install the Intercom Messenger in your mobile app, authenticate your signed-in users securely, and confirm everything is working before you ship.
The steps for a full and secure Messenger install are:
Choose your install type.
Install and initialize the SDK.
Authenticate signed-in users.
Test your installation.
Note:
This is the new Messenger install experience, rolling out gradually. If your workspace hasn't been switched over yet, use Install and use Intercom in your mobile app instead.
You'll need a contracted plan or monthly plan to install the Messenger, and access to your app's codebase (or a developer who does). The Messenger supports iOS, Android, and React Native.
Choose your install type
Go to Settings > Channels > Messenger Live Chat >Overview , find the Mobile app card and select Install on mobile app.
Select your install type
You'll be asked "What information does your team need in your inbox?" and shown two options:
Non signed-in users (quickest to install) — Conversations aren't linked to user details. You can complete the additional setup later to identify signed-in users.
Signed-in users and non signed-in users — Conversations from signed-in users include relevant details, giving your team the context they need to provide personalized support. Requires app and backend changes.
Select the option that fits your business, then click Continue to move on to the installation steps below.
Install and initialize the SDK
This section covers steps 1–3 of the install. It only takes a few minutes, and applies whether or not you're identifying signed-in users.
1. Choose your platform
Use the Mobile app platform dropdown to choose which platform you're installing on: iOS, Android, or React Native. The steps below use iOS as an example — the shape of the flow is the same for other platforms, with platform-specific code.
2. Add the SDK dependency
Choose your install method from the dropdown (for iOS, this includes Swift Package Manager and CocoaPods). For Swift Package Manager:
In Xcode, navigate to File > Add Packages.
When prompted, enter the Intercom iOS SDK (software development kit) repository URL:
.package(url: "https://github.com/intercom/intercom-ios", from: "18.0.0")
Select the version of Intercom you wish to use. We recommend using the latest version.
Click Add Package and Intercom will automatically be downloaded as a dependency for your project.
3. Initialize Intercom
You'll see your platform-specific API key (application programming interface key) on this step — for example, your iOS API Key. Click Copy code to grab it, or Regenerate API key if you need a new one.
Call the following in your application delegate method:
import UIKit
import Intercom
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
func application(_ application: UIApplication, didFinishLaunchingWithOptions
launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
Intercom.setApiKey("YOUR_IOS_API_KEY", forAppId: "YOUR_APP_ID")
Intercom.setLauncherVisible(true)
// If you have identifying information for your user you can use
// `Intercom.loginUser(with:completion:)`
Intercom.loginUnidentifiedUser()
return true
}
}Authenticate signed-in users
This section covers steps 4–7, and needs changes on both your mobile app and your backend.
4. Choose your backend language
Use the dropdown to choose the language your backend is written in (for example, Node).
Tip: This step needs someone to generate tokens server-side. If that's not you, click Invite a developer to bring a teammate in to finish it with you.
5. Generate a token for each customer
On your server, generate a signed JSON Web Token (JWT) for each logged-in user:
const jwt = require('jsonwebtoken');
const token = jwt.sign(
{ user_id: user.id, email: user.email },
process.env.INTERCOM_SECRET_KEY,
{ algorithm: 'HS256', expiresIn: '1h' },
);
You'll need your workspace's secret key for this — it's shown (masked) on this step. Keep this key on your server. Never include it in browser or app code.
Note: Keys are scoped to platforms, and your workspace can have more than one. You can create, rotate, or decode a key from your Messenger security settings.
6. Configure the JWT in your mobile app
Pass the token your server generated into your existing Intercom initialization call, alongside your app_id:
Intercom({
app_id: 'your_app_id',
intercom_user_jwt: user.jwt,
});
7. Identify users
Once the JWT is wired in, identify the logged-in user with:
Intercom.loginUser(
ICPRegistrationOptions.create(userJwt: user.jwt)
) { result in }Important: Older app versions won't send signed tokens. If your app is already live, customer data won't be connected until your users update the app. We recommend a forced update to get everyone onto a version that sends the JWT.
Test your installation
Once you've completed the steps above, click Test your installation. This confirms the Messenger and (if applicable) your JWT setup are working correctly before you ship to your users.
If something's not working, check:
The app_id in your init call matches your workspace.
Your secret key hasn't been rotated or revoked since you generated your last token.
The user_id you're passing to the SDK matches the one encoded in the JWT payload.
Once everything checks out, you're live. You can check on install status any time from Settings > Channels > Messenger Live Chat > Overview, under Installation locations.
Note: Session length is configurable from Settings > Channels > Messenger Live Chat > Security, under Session duration. Customers are asked to reauthenticate once that period expires.
💡 Tip: Need more help? Get support from our Community Forum. Find answers and get help from Intercom Support and Community Experts.
Related Articles
Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts