Platform Setup

After installing the crisp_chat package, configure settings for the targets you ship. Web and desktop need little or no native setup; Android and iOS need the steps below. Push notification setup is mobile-only — see Firebase Setup.

Enable Flutter targets

If your project was created before adding Web or desktop, enable the platforms you need:

bash

flutter create . --platforms=web,macos,windows,linux

See the API availability matrix for behavior differences per platform.

Android

1. Internet Permission

Add Internet permission to your android/app/src/main/AndroidManifest.xml:

xml

<uses-permission android:name="android.permission.INTERNET"/>

2. Compile SDK Version

Set compileSdkVersion to 36 (or higher) in android/app/build.gradle:

groovy

android {
    compileSdkVersion 36
}

3. Minimum SDK Version

Set minSdkVersion to 23 (or higher) in android/app/build.gradle:

groovy

defaultConfig {
    minSdkVersion 23
}

4. FileProvider (Optional)

If your app already declares a FileProvider in AndroidManifest.xml, add Crisp's authority and path for the file upload feature:

xml

<provider android:name="androidx.core.content.FileProvider"
  android:authorities="${applicationId}.fileprovider;${applicationId}.im.crisp.client.uploadfileprovider"
  android:exported="false"
  android:grantUriPermissions="true"
  tools:replace="android:authorities">
  <meta-data android:name="android.support.FILE_PROVIDER_PATHS"
    android:resource="@xml/file_paths"
    tools:replace="android:resource" />
</provider>

And in res/xml/file_paths.xml:

xml

<files-path name="crisp_sdk_attachments" path="im.crisp.client/attachments/" />

iOS

1. Privacy Permissions (required)

Add the following keys to ios/Runner/Info.plist. Since Crisp iOS SDK 3.x, NSCameraUsageDescription and NSMicrophoneUsageDescription are required — if either is missing, the SDK refuses to start the chat and shows a missing-configuration screen instead. NSPhotoLibraryAddUsageDescription is recommended so users can save photos from chat.

xml

<!-- Required -->
<key>NSCameraUsageDescription</key>
<string>Used to take photos and make video calls in chat</string>
<key>NSMicrophoneUsageDescription</key>
<string>Used for voice messages and audio/video calls in chat</string>
<!-- Recommended -->
<key>NSPhotoLibraryAddUsageDescription</key>
<string>Used to save photos from chat</string>

2. Minimum Deployment Target

The Crisp iOS SDK (~> 3.0.1) requires iOS 14.0+ and Xcode 16.3+ (the SDK is built with Swift tools 6.1). Ensure your ios/Podfile has:

ruby

platform :ios, '14.0'

Also set Minimum Deployments to 14.0 (or higher) on the Runner target in Xcode. If your app uses Firebase push notifications, use 15.0+ instead — see Firebase requires iOS 15.0.

Swift Package Manager recommended

Crisp has deprecated CocoaPods distribution and stops publishing new versions there at the end of September 2026. Version 3.0.1 is available on CocoaPods, so CocoaPods builds keep working, but Swift Package Manager (the default in Flutter 3.44+) is the recommended path going forward. See CocoaPods vs Swift Package Manager.

Why upgrade to 3.x

Crisp iOS SDK 3.0.1 ties chat sessions to a Crisp-issued token, so only the device that started a conversation can reopen it. Crisp will start requiring these tokens in the coming months; older SDKs (including 2.x) will not be able to reopen conversations after that.

Enable video calls (iOS only)

Video and audio calls are included automatically on every iOS build. Since Crisp iOS SDK 3.0, calls are built into the single Crisp SDK — there is no separate WebRTC variant, no Podfile flag, and no environment variable to set. Calls are initiated from the Crisp chat UI when your Crisp workspace supports them.

FlutterCrispChat.isVideoCallsSupported() always returns true on iOS. The only setup needed is the camera and microphone usage descriptions from step 1, which are required for the chat to start at all.

Migrating from 2.x

If you previously enabled calls with the WebRTC variant, remove the old flags — the plugin no longer reads them and they are ignored:

CocoaPods: delete $CrispChatWebRTC = true from ios/Podfile.
SPM: stop setting CRISP_CHAT_WEBRTC=true (shell, CI, or Xcode scheme environment variables).

Then run a clean build so SPM/CocoaPods re-resolve dependencies:

bash

flutter clean && flutter pub get
# CocoaPods only:
cd ios && rm -f Podfile.lock && pod install --repo-update && cd ..

Limitations:

Android: native video/audio calls are not supported yet by the Crisp Android SDK.
Mac Catalyst: Crisp calls are not supported.

Web / desktop: video calls work through the web chatbox when enabled in your Crisp dashboard — no extra native setup.

Crisp dashboard (Android & iOS)

Before opening chat on native mobile targets:

Disable Lock the chatbox to website domain (and subdomains) under Settings → Website Settings → Chatbox & Email Settings → Chatbox Security. See Configuration — Chatbox Security.

Web

No native Crisp SDK install. When you call openCrispChat, the plugin loads the official script from https://client.crisp.chat/l.js and opens the Crisp chatbox in the page.

Ensure Web is enabled for your app (flutter create . --platforms=web if needed).
Use a valid Website ID from the Crisp Dashboard.
Identity verification: only set User.signature when it is a real HMAC-SHA256 hex string from your server (32+ hex characters). Fake placeholders can leave the chat on the loading skeleton.
Content-Security-Policy (optional): if your site uses CSP, allow scripts and connections to https://client.crisp.chat and https://*.crisp.chat.
REST API on web: getUnreadMessageCount / markMessagesAsRead accept credentials in Dart; those values are visible in the browser — use a backend proxy in production.
Domain lock (optional): if Lock the chatbox to website domain is enabled, host the app on an allowed domain or subdomain and verify the page origin if chat fails to connect. See Configuration — Chatbox Security.

openChatboxFromNotification, setOnNotificationTappedCallback, CrispConfig.enableNotifications, and modalPresentationStyle have no effect on Web.

More detail: Supported Platforms — Web.

Desktop (macOS, Windows, Linux)

Desktop uses the same Crisp Web Chat SDK inside an embedded window (desktop_webview_window), or opens the system browser if WebView is unavailable.

1. `main()` — title bar helper (embedded WebView)

Add this before runApp when you target desktop:

dart

import 'package:desktop_webview_window/desktop_webview_window.dart';
import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';

Future<void> main(List<String> args) async {
  WidgetsFlutterBinding.ensureInitialized();

  if (!kIsWeb &&
      (defaultTargetPlatform == TargetPlatform.macOS ||
          defaultTargetPlatform == TargetPlatform.windows ||
          defaultTargetPlatform == TargetPlatform.linux)) {
    if (runWebViewTitleBarWidget(args)) {
      return;
    }
  }

  runApp(const MyApp());
}

2. macOS — network entitlement (embedded chat)

If your macOS app uses the App Sandbox, enable Outgoing Connections (Client) in macos/Runner/DebugProfile.entitlements and Release.entitlements:

xml

<key>com.apple.security.network.client</key>
<true/>

Without this, the WebView stays blank. The plugin loads embed HTML from a temporary file:// page so external l.js can load (WKWebView blocks scripts on data: URLs).

3. Windows — WebView2

Install the WebView2 Runtime for an embedded chat window. Without it, chat opens in the default browser.

4. Linux — WebKitGTK

bash

sudo apt install libwebkit2gtk-4.1-dev

(Or libwebkit2gtk-4.0-dev on older distributions.)

5. Domain lock

Disable Lock the chatbox to website domain for desktop chat:

Embedded WebView loads chat from a temporary file:// page — there is no website origin to match (same constraint as mobile).
Browser fallback opens https://app.crisp.chat/website/{id}/, which also conflicts with domain lock.

See Configuration — Chatbox Security.

Browser fallback

When WebView is unavailable, openCrispChat opens Crisp in the system browser. In that mode, resetCrispChatSession, session setters, and getSessionIdentifier are no-ops or return null because there is no embedded bridge.

More detail: Supported Platforms — Desktop.

Next Steps

Supported Platforms — Platform support matrix for Android, iOS, Web, and desktop
Quick Start — Open your first chat in 5 minutes

For push notification setup (Firebase, APNs) on Android and iOS only, see Firebase Setup.

Platform Setup ​

Enable Flutter targets ​

Android ​

1. Internet Permission ​

2. Compile SDK Version ​

3. Minimum SDK Version ​

4. FileProvider (Optional) ​

iOS ​

1. Privacy Permissions (required) ​

2. Minimum Deployment Target ​

Enable video calls (iOS only) ​

Migrating from 2.x ​

Crisp dashboard (Android & iOS) ​

Web ​

Desktop (macOS, Windows, Linux) ​

1. main() — title bar helper (embedded WebView) ​

2. macOS — network entitlement (embedded chat) ​

3. Windows — WebView2 ​

4. Linux — WebKitGTK ​

5. Domain lock ​

Browser fallback ​

Next Steps ​

Platform Setup

Enable Flutter targets

Android

1. Internet Permission

2. Compile SDK Version

3. Minimum SDK Version

4. FileProvider (Optional)

iOS

1. Privacy Permissions (required)

2. Minimum Deployment Target

Enable video calls (iOS only)

Migrating from 2.x

Crisp dashboard (Android & iOS)

Web

Desktop (macOS, Windows, Linux)

1. `main()` — title bar helper (embedded WebView)

2. macOS — network entitlement (embedded chat)

3. Windows — WebView2

4. Linux — WebKitGTK

5. Domain lock

Browser fallback

Next Steps