# Intercom Messenger

- Tool: FlutterFlow
- Difficulty: Intermediate
- Time required: 45 minutes
- Last updated: July 2026

## TL;DR

To add Intercom Messenger live chat to a FlutterFlow app, use a Custom Action built on the official `intercom_flutter` pub.dev package. Three Dart actions handle initialization, user identification, and opening the chat widget. The SDK renders a native overlay on iOS and Android — it does not work in FlutterFlow's web preview, so you must test with a real device build.

## Adding Intercom Live Chat to Your FlutterFlow App

Intercom Messenger is different from Intercom's REST API for contacts and conversations. The Messenger is the live chat widget — the floating button that pops open a full-screen support panel where users can message your team in real time. Getting this widget into a FlutterFlow app does not involve API Calls or JSON Path: it requires the `intercom_flutter` package, which wraps Intercom's native iOS and Android SDKs in Dart code that FlutterFlow can call through Custom Actions.

The three-action pattern is straightforward: you initialize the SDK once at app launch with your Intercom App ID and platform-specific API keys (iOS SDK key and Android API key), you call a user-identification action after the user logs in so Intercom knows who is chatting, and then you call `displayMessenger()` whenever the user taps a Help or Support button. The Messenger appears as a native overlay on top of your app — your FlutterFlow UI does not need to host any chat UI widgets. Intercom handles message delivery, operator assignment, and the full conversation thread.

One important caveat: because `intercom_flutter` is a native SDK, it does not render inside FlutterFlow's browser-based Run mode or web preview. When you tap the action in preview, nothing will happen. You must download your project and build it for iOS or Android (or use FlutterFlow's Test Mode on a connected device) to see the Messenger appear. Plan your testing workflow accordingly before starting. Pricing for Intercom includes the Messenger in its seat-based plans — verify current plan details on intercom.com, as Messenger access depends on your workspace tier.

## Before you start

- An Intercom workspace on a plan that includes Messenger (verify current plan requirements at intercom.com)
- Your Intercom App ID (from Intercom Settings → Installation → Mobile)
- iOS SDK key and Android API key from the same Installation page in Intercom Settings
- A FlutterFlow project on a plan that supports Custom Code and Custom Actions
- Access to a physical iOS or Android device (or Xcode Simulator / Android emulator) for testing — the Messenger will not appear in FlutterFlow's web preview

## Step-by-step guide

### 1. Collect your Intercom credentials and add the pub.dev dependency

Log into your Intercom workspace and navigate to Settings → Installation. Choose Mobile and select your platform (iOS or Android). You will find three credentials you need: App ID (the same for both platforms), iOS API Key (labeled 'iOS SDK Key'), and Android API Key. Copy all three to a safe place. The iOS and Android API keys are client SDK keys designed to be embedded in mobile apps — they are not secret API keys in the same sense as a backend token, but you should still keep them in your Custom Action parameters rather than hardcoding them as plain strings scattered through your code. Next, open your FlutterFlow project and navigate to the left sidebar. Click Custom Code, then look for the Dependencies section (or go to Settings → App Settings → Pub Dependencies depending on your FlutterFlow version). Click + Add Dependency and type `intercom_flutter`. Enter the latest stable version number — check pub.dev/packages/intercom_flutter for the current version (for example, `4.2.1`). Click Save. FlutterFlow will register this dependency; it will be included in the pubspec.yaml when the project is compiled. You do not need to run `flutter pub get` manually — FlutterFlow handles that during the build process.

```
// pubspec.yaml dependency (FlutterFlow adds this for you)
dependencies:
  intercom_flutter: ^4.2.1  // check pub.dev for the latest stable version
```

**Expected result:** The `intercom_flutter` dependency appears in your FlutterFlow Custom Code dependencies list. No errors appear in the FlutterFlow dependency panel.

### 2. Create the initIntercom Custom Action

In the FlutterFlow left nav, click Custom Code → + Add → Action. Name it `initIntercom`. In the code editor, write the Dart function that initializes the Intercom SDK. The function calls `Intercom.instance.initialize()` with three parameters: `appId`, `iosApiKey`, and `androidApiKey`. These should be defined as Action Arguments (function parameters) in FlutterFlow's argument panel so you can pass them from your page without hardcoding values in the Dart file. In the Arguments tab of the Custom Action editor, add three String arguments: `appId`, `iosApiKey`, and `androidApiKey`. Then write the implementation. This action must run before any other Intercom call — call it once at the very start of your app. The best place is on the splash screen or the very first page's On Page Load action, as the final step (or a parallel action) after any other initialization. If your app uses Supabase Auth or Firebase Auth, initialize Intercom after authentication is ready so the SDK starts in an identified or anonymous state correctly. After pasting the code, click Save. FlutterFlow will validate the Dart syntax — fix any red underlines before proceeding.

```
// Custom Action: initIntercom
import 'package:intercom_flutter/intercom_flutter.dart';
import 'package:flutter/foundation.dart' show defaultTargetPlatform, TargetPlatform;

Future<void> initIntercom(
  String appId,
  String iosApiKey,
  String androidApiKey,
) async {
  await Intercom.instance.initialize(
    appId,
    iosApiKey: iosApiKey,
    androidApiKey: androidApiKey,
  );
}
```

**Expected result:** The `initIntercom` Custom Action saves without Dart errors and appears in your Custom Code list. The three string arguments (appId, iosApiKey, androidApiKey) show in the Arguments panel.

### 3. Create the loginIntercomUser Custom Action

After initialization, Intercom needs to know who the current user is so conversations in your Intercom inbox are attributed to real contacts rather than anonymous sessions. Create a second Custom Action named `loginIntercomUser`. Add three String arguments: `userId`, `userEmail`, and optionally `userName`. In the Dart code, call `Intercom.instance.loginIdentifiedUser()` with `userId` and optionally update the user's details with `Intercom.instance.updateUser()`. This action should be called right after the user successfully logs in to your app — place it in the Action Flow Editor on your Login page's On Login Success event, after your auth action (Supabase Login, Firebase Sign In, etc.) completes. If a user logs out, you should also call `Intercom.instance.logout()` — create a third small action `logoutIntercomUser` that does exactly that. Pass the user's real ID and email from your auth system (Supabase user ID, Firebase UID) so Intercom correctly links conversations to contacts in your workspace. Custom attributes (like plan type or onboarding step) can be passed via `Intercom.instance.updateUser(userAttributes: Attributes(customAttributes: {'plan': 'pro'}))` inside this same action if needed.

```
// Custom Action: loginIntercomUser
import 'package:intercom_flutter/intercom_flutter.dart';

Future<void> loginIntercomUser(
  String userId,
  String userEmail,
  String userName,
) async {
  await Intercom.instance.loginIdentifiedUser(
    userId: userId,
  );
  await Intercom.instance.updateUser(
    email: userEmail,
    name: userName,
  );
}

// Companion action: logoutIntercomUser
Future<void> logoutIntercomUser() async {
  await Intercom.instance.logout();
}
```

**Expected result:** The `loginIntercomUser` Custom Action saves successfully. In your Action Flow Editor, you can select it from the Custom Actions list and see three input fields for userId, userEmail, and userName.

### 4. Create the showMessenger action and wire it to a support button

The third and final Custom Action is the simplest: `showMessenger`. It calls `Intercom.instance.displayMessenger()`, which opens the Intercom chat overlay. Create the Custom Action with no arguments and paste the one-liner implementation. Once saved, go to the page or widget where you want the support button to live. A common pattern is a floating action button (FAB) on the home screen or a 'Get help' TextButton in an app drawer. Click on the button widget, open its Actions panel on the right side of FlutterFlow, click + Add Action, and select Custom Action → showMessenger. That is the entire configuration — one action, no parameters. To also close the Messenger programmatically (for example, if your app needs to redirect away), you can create a fourth action `hideMessenger` that calls `Intercom.instance.hideMessenger()`. You can optionally add an unread message badge to your support button by reading `Intercom.instance.unreadConversationCount()` in a Custom Function and binding the result to a badge widget on the button — this gives users a visual cue that your support team has replied.

```
// Custom Action: showMessenger
import 'package:intercom_flutter/intercom_flutter.dart';

Future<void> showMessenger() async {
  await Intercom.instance.displayMessenger();
}

// Optional: Custom Function to get unread count
import 'package:intercom_flutter/intercom_flutter.dart';

Future<int> getIntercomUnreadCount() async {
  return await Intercom.instance.unreadConversationCount();
}
```

**Expected result:** The showMessenger Custom Action is wired to your button. In the Action Flow Editor, the button's on-tap actions list shows showMessenger as a single action with no arguments required.

### 5. Test on a real device build (not web preview)

Custom Actions using native SDKs like `intercom_flutter` do not run inside FlutterFlow's browser-based Run mode or the in-browser Preview panel. When you click the support button in web preview, nothing will happen and you will not see an error — the action simply silences itself when the native bridge is unavailable. To test the real Messenger, you have two options: use FlutterFlow's Test Mode on a connected physical device (Settings → Test Mode → select your connected device), or download the project source code and build it locally with Xcode or Android Studio. If you are using FlutterFlow's Test Mode, connect your phone via USB, enable developer mode and USB debugging, and select the device in FlutterFlow. Tap your support button in the app running on the device — you should see the Intercom Messenger slide up as a native overlay. For iOS builds, verify that the Info.plist includes usage descriptions for camera and photo library if you plan to allow file sharing in chat (Intercom's Messenger can share attachments). For Android, confirm the minSdkVersion in your FlutterFlow project's Android settings is compatible with the `intercom_flutter` package requirements (check the package's README on pub.dev). If you receive a MissingPluginException, rebuild the app from scratch — sometimes Hot Reload does not register new native plugins; a full rebuild is required.

**Expected result:** On a real iOS or Android device, tapping the support button causes the Intercom Messenger to slide up as a native overlay. The Intercom workspace receives the conversation attributed to the logged-in user.

## Best practices

- Call `initIntercom` on app start before any other Intercom method — treat it like initializing your analytics or auth library, not something to lazy-load per screen.
- Always call `loginIntercomUser` with a stable user ID (Supabase UID or Firebase UID) immediately after authentication — this links every conversation to the correct contact in your Intercom workspace.
- Call `logoutIntercomUser` when the user signs out to clear the session — otherwise a different user on the same device will see the previous user's conversation history.
- Keep the Messenger trigger on a clearly labeled button ('Get help', 'Support', or a chat-bubble icon) in a consistent location — a FAB in the bottom-right is the most discoverable placement.
- Pass custom attributes (plan tier, current screen, onboarding step) in `updateUser` so support agents see context before they respond — this dramatically improves first response quality.
- Test the full flow on both iOS and Android devices before shipping — platform-specific SDK behaviors can differ, and the `intercom_flutter` package may have platform-specific minimum version requirements.
- Do not rely on the unread message count badge from a polling timer — use `Intercom.instance.unreadConversationCount()` only on app foreground events to avoid unnecessary SDK calls.
- Keep the Intercom App ID and platform API keys in FlutterFlow's App Constants rather than typing them inline in action parameters — this makes it easy to switch between staging and production Intercom workspaces.

## Use cases

### SaaS app with in-app customer support chat

A B2B SaaS startup builds their FlutterFlow mobile companion app with an embedded Intercom Messenger so users can message support without leaving the app. After a user logs in with Supabase Auth, the app calls the identify action so every conversation in the Intercom workspace shows the user's name, email, and plan.

Prompt example:

```
Add a floating support button (FAB) to the bottom-right corner of the home screen. When tapped, it opens the Intercom Messenger overlay so users can chat with the support team.
```

### E-commerce app with order-based support conversations

An e-commerce Flutter app shows a 'Need help?' button on the order detail screen. Tapping it opens Intercom Messenger, pre-identified with the user's email and a custom attribute for the order number — so the support agent immediately sees context about which order the customer is asking about.

Prompt example:

```
On the order detail page, add a Help button. When tapped, identify the user in Intercom with their email and an order_number custom attribute, then open the Messenger.
```

### Onboarding flow with contextual live chat

A fintech app's multi-step onboarding wizard includes a persistent 'Chat with us' link in the bottom bar. If a user gets stuck during KYC document upload, tapping the link opens Intercom Messenger. The identify action passes the current onboarding step as a custom attribute so support agents see exactly where the user dropped off.

Prompt example:

```
During the onboarding flow, show a 'Get help' text button at the bottom of each step. Tapping it should open Intercom Messenger with the current step name passed as a custom user attribute.
```

## Troubleshooting

### Tapping the support button in FlutterFlow web preview does nothing

Cause: The `intercom_flutter` package is a native SDK that uses platform channels — these do not exist in the browser environment that FlutterFlow's preview uses.

Solution: This is expected behavior. Test on a real iOS or Android device using FlutterFlow Test Mode or a local build. There is no workaround for the preview environment — native SDKs simply cannot run there.

### MissingPluginException: No implementation found for method 'initialize' on channel 'com.intercom.intercom_flutter'

Cause: The native plugin was added after the app was last built, and a Hot Reload/Restart did not register the new platform channel.

Solution: Stop the running app completely and perform a full rebuild. In FlutterFlow Test Mode, end the test session and start a new one. If building locally with Xcode or Android Studio, run a clean build (`flutter clean` then rebuild). Hot reloads cannot register new native plugins.

### Intercom shows 'Anonymous' user instead of the logged-in user's name and email

Cause: The `loginIntercomUser` action was not called after login, or it was called before `initIntercom` completed.

Solution: Ensure your Action Flow sequence is: (1) initIntercom on app start, then (2) loginIntercomUser immediately after successful authentication. Check your Login page's action list and confirm loginIntercomUser appears after the Supabase/Firebase sign-in action. Also verify you are passing the correct userId — it must be a stable, non-changing string unique to the user (Supabase UID or Firebase UID works well).

### Build fails on iOS with 'ld: framework not found IntercomSDK' or similar linker error

Cause: The `intercom_flutter` package version requires a specific iOS deployment target or a CocoaPods update, and the Xcode project has not been properly configured.

Solution: Check the `intercom_flutter` pub.dev README for the minimum iOS deployment target (usually iOS 13 or 14). In FlutterFlow's iOS settings (Settings → iOS App Settings), ensure the deployment target matches. If building locally, run `pod install` in the ios/ directory after adding the dependency, then rebuild. If using FlutterFlow's export, the generated project should handle this automatically on first build.

## Frequently asked questions

### Does this integration work for Flutter web, not just iOS and Android?

The `intercom_flutter` package has limited web support and its behavior depends on the specific package version. FlutterFlow's web build uses the browser renderer, and native SDK features often degrade or break in web contexts. For reliable Messenger support across platforms, use Intercom's JavaScript integration for your web app separately — the Custom Action approach is best for native iOS and Android apps.

### Is the Intercom App ID or iOS/Android API key a secret that needs to be hidden?

These are client SDK keys — they are designed to be embedded in mobile apps and are not equivalent to server-side secret API keys. However, someone with your App ID could theoretically create fake Intercom sessions. Best practice is to keep them in App Constants rather than committing them as plain strings in shared code, and to enable identity verification in Intercom (which requires a separate HMAC hash generated server-side) if your app serves sensitive data.

### Can I use Intercom's Articles (knowledge base) widget instead of live chat?

Yes. The `intercom_flutter` package exposes `Intercom.instance.displayHelpCenter()` to open the Articles / Help Center overlay, and `Intercom.instance.displayArticle(articleId)` to open a specific article. You can create a separate Custom Action for each of these and wire them to help-icon buttons on any screen in your app.

### How do I handle Intercom push notifications for new messages?

Intercom can deliver push notifications when a support agent replies to a conversation. On iOS, this requires configuring push notification certificates in your Intercom workspace and adding push notification permissions to your FlutterFlow app (Settings → Permissions → Push Notifications). On Android, you need to pass the Firebase Cloud Messaging (FCM) token to Intercom using `Intercom.instance.sendTokenToIntercom(token)` in your Custom Action. If you need a managed setup for this, RapidDev builds FlutterFlow integrations including push notification flows — book a free scoping call at rapidevelopers.com/contact.

### What happens to existing Intercom conversations when the user logs out and back in?

When you call `logoutIntercomUser`, Intercom clears the session on the device. When the user logs in again and you call `loginIntercomUser` with the same userId, Intercom restores their conversation history — the conversations are stored in the Intercom workspace by user ID, not on the device. Anonymous conversations started before login are not automatically merged with the identified user's history.

---

Source: https://www.rapidevelopers.com/flutterflow-integrations/intercom-messenger
© RapidDev — https://www.rapidevelopers.com/flutterflow-integrations/intercom-messenger