Flutter Crisp Chat

Appearance

Platform-Specific Issues ​

Android ​

FileProvider conflict ​

If your app already declares a FileProvider, you may see:

Manifest merger failed: Attribute provider#androidx.core.content.FileProvider@authorities

Fix: Merge the Crisp authority into your existing FileProvider declaration:

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 add to res/xml/file_paths.xml:

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

ProGuard / R8 issues ​

If you're using code shrinking and encounter crashes, ensure ProGuard rules for Crisp are included. The Crisp SDK typically bundles its own rules, but if issues persist, add:

proguard
-keep class im.crisp.client.** { *; }

Camera crash on some devices ​

Some devices (especially Xiaomi/Redmi) may crash when using the camera feature. Ensure you're using Crisp Android SDK 2.0.5 or later, which includes a fix for this.

On some devices (Xiaomi/Redmi, Android 12+), mailto: links in the chat may fail to open the email app. This was fixed in version 2.3.0 (#57).

Keyboard pushes view up ​

If the keyboard pushes the chat view up unexpectedly, ensure you're using Crisp Android SDK 2.0.11 or later. Fixed in version 2.2.5 (#45).

iOS ​

Minimum deployment target error ​

text
# SPM
The package product 'Crisp' requires minimum platform version 14.0 for the iOS platform, but this target supports 13.0

# CocoaPods
Specs satisfying the `Crisp (~> 3.0.1)` dependency were found, but they required a higher minimum deployment target.

The Crisp iOS SDK ~> 3.0.1 requires iOS 14.0+ and Xcode 16.3+ (Swift tools 6.1).

Fix: Update your ios/Podfile:

ruby
platform :ios, '14.0'

Set Minimum Deployments to 14.0 on the Runner target in Xcode too, then delete ios/Podfile.lock and run pod install --repo-update (CocoaPods) or flutter clean && flutter pub get (SPM).

Push notifications not working in development ​

Crisp iOS push notifications only work with production APNs. They will not be received when using development provisioning profiles or sandbox mode.

Chat shows a configuration error / doesn't start on iOS ​

Symptom: openCrispChat presents a missing-configuration screen instead of the chat, or the chat never starts.

Cause: Crisp iOS SDK 3.x refuses to start unless both NSCameraUsageDescription and NSMicrophoneUsageDescription are present in the app's Info.plist.

Fix: Add the keys below (see Missing privacy permissions), then do a clean rebuild (flutter clean && flutter run).

Missing privacy permissions ​

If the chat shows a configuration error on open, or the app crashes when the user tries to take a photo or access the camera in chat:

Fix: Add the keys to ios/Runner/Info.plist. Camera and microphone descriptions are required by Crisp iOS SDK 3.x; the photo library key is recommended:

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>

Reset session crash on iOS ​

If resetCrispChatSession crashes on iOS, ensure you're using version 2.0.9 or later, which fixed this issue (#20).

iOS unread count not clearing ​

After opening chat, reading all operator messages, and closing the UI, getUnreadMessageCount() may still return a non-zero value. A direct GET /v1/website/{website_id}/conversation/{session_id} shows the same stale unread.visitor — this is a Crisp iOS SDK limitation (read receipts not synced to the server).

Workaround:

dart
await FlutterCrispChat.markMessagesAsRead(
  websiteId: websiteId,
  identifier: identifier,
  key: key,
);

Verify: Run ./scripts/verify_unread_read_receipts.sh full with your REST credentials. If manual PATCH /read clears the count but reading in chat does not, file an issue using docs/crisp-sdk-ios-unread-issue.md.

Compare with Android using the same REST GET steps — if Android clears unread.visitor after reading but iOS does not, the bug is iOS-specific.

CocoaPods vs Swift Package Manager ​

The plugin supports both CocoaPods and Swift Package Manager (SPM) for iOS dependency management.

CocoaPods deprecated upstream

Crisp has deprecated CocoaPods distribution and stops publishing new versions there at the end of September 2026. Crisp iOS SDK 3.0.1 is on CocoaPods, so CocoaPods builds still work, but SPM is the recommended path.

Enabling SPM

  • Flutter 3.24+: flutter config --enable-swift-package-manager, then flutter run / flutter build ios (Flutter migrates the Xcode project automatically).
  • Flutter 3.44+: SPM is the default for iOS/macOS. Flutter uses SPM for plugins that ship a Package.swift; others fall back to CocoaPods with a warning.
  • Disable per project: flutter: config: enable-swift-package-manager: false in pubspec.yaml.

Video calls (CocoaPods and SPM)

No build flag is needed — since Crisp iOS SDK 3.0, audio/video calls are built into the single Crisp SDK. The old CrispWebRTC product / Crisp/CrispWebRTC subspec no longer exist, and the plugin ignores $CrispChatWebRTC (Podfile) and CRISP_CHAT_WEBRTC (SPM env var); remove them if you set them before. See Enable video calls (iOS only).

Flutter framework dependency

Flutter injects the Flutter framework when building through the CLI (pre-action script + local package overrides). Plugin Package.swift files do not hardcode a FlutterFramework path — same pattern as first-party Flutter plugins.

If SPM resolution fails, try flutter clean, delete ios/Flutter/ephemeral, and rebuild. See Flutter SPM docs for app developers.

Target Integrity: Firebase requires iOS 15.0 but target supports 14.0 ​

Symptom: Xcode error when using SPM:

text
The package product 'firebase-core' requires minimum platform version 15.0 for the iOS platform, but this target supports 14.0

Cause: firebase_core / firebase_messaging (and recent Firebase iOS SDKs) require iOS 15.0+ when resolved via Swift Package Manager. The app or Xcode project may still declare 14.0 (the minimum for Crisp alone).

Fix:

  1. Set iOS Deployment Target to 15.0 or higher in Xcode (Runner target → General → Minimum Deployments).
  2. Update ios/Podfile: platform :ios, '15.0'
  3. In ios/Runner.xcodeproj/project.pbxproj, set IPHONEOS_DEPLOYMENT_TARGET = 15.0 for Debug, Release, and Profile.
  4. Regenerate config: flutter clean && flutter pub get && cd ios && pod install && cd ..

crisp_chat itself supports iOS 14.0+ when you do not use Firebase. If your app includes Firebase push notifications, use iOS 15.0+ as the app minimum.

Web ​

Chat stuck on loading spinner (skeleton UI) ​

The gray/blue placeholder bars mean the chat shell opened but the session did not connect.

  1. Confirm websiteID is correct.
  2. Identity verification: only pass User.signature when it is a real HMAC-SHA256 hex string from your server (at least 32 hex characters). Placeholder values are ignored by the plugin; if you set a fake signature manually, Crisp may stay on the skeleton screen.
  3. Allow third-party cookies for crisp.chat in Chrome (Settings → Privacy → third-party cookies). Crisp needs cookies for the visitor session.
  4. Check DevTools → Network for failed requests to client.crisp.chat or storage.crisp.chat.
  5. Hard-refresh the page (Cmd+Shift+R) after upgrading the plugin so l.js is not cached from an old run.

Domain lock enabled ​

If Lock the chatbox to website domain is enabled in the Crisp dashboard:

  • Symptom: skeleton UI / session never connects
  • Check: run window.location.origin in DevTools and compare with allowed domains in the dashboard
  • Fix: add the origin to the lock list, disable domain lock, or deploy to an allowed host

See Configuration — Chatbox Security.

Chat does not appear ​

  1. Confirm openCrispChat was called with a valid websiteID.
  2. If you use a Content-Security-Policy, allow https://client.crisp.chat and Crisp API hosts.
  3. Check the browser console for blocked scripts.

REST API keys in web builds ​

getUnreadMessageCount and markMessagesAsRead use your Crisp REST credentials from Dart. On Web, those values are visible to users — prefer a backend proxy for production.

Desktop (macOS, Windows, Linux) ​

Domain lock enabled ​

If Lock the chatbox to website domain is enabled in the Crisp dashboard:

  • Embedded WebView loads chat from a temporary file:// page — disable domain lock (same as mobile).
  • Browser fallback opens https://app.crisp.chat/website/{id}/, which is also incompatible with domain lock — install WebView2 (Windows) or WebKitGTK (Linux) for embedded chat instead.

See Configuration — Chatbox Security.

Embedded WebView does not open ​

  • Windows: Install the WebView2 Runtime.
  • Linux: Install WebKitGTK (libwebkit2gtk-4.1-dev or libwebkit2gtk-4.0-dev).
  • If WebView is unavailable, the plugin opens Crisp in the system browser instead.

Session APIs return null after browser fallback ​

resetCrispChatSession, setSessionString, and getSessionIdentifier require an active desktop WebView. They are no-ops (or return null) when chat was opened in an external browser.

runWebViewTitleBarWidget in main ​

When using desktop_webview_window, add the title-bar helper to your app main — see Supported platforms.

Need More Help? ​

Next Steps ​