Flutter

Flutter bridge over the native Android and iOS chat SDKs; the native chat screen is presented, so there is no Dart-side UI to compose. Flutter 3.3+, iOS 14+, Android minSdk 24 with JDK 17 and mavenCentral() in your Gradle repositories.

Install and quick startlink

flutter pub add newinstance_chat

final chat = NewinstanceChat(NewinstanceChatConfig(apiKey: 'sk_live_abc123'));
await chat.ready;
await chat.setUser(ChatUser(customerName: 'Ada', customerEmail: 'ada@example.com'));
await chat.initialize();
await chat.openChat();

NewinstanceChatConfig(apiKey, baseUrl?, transport?, initialMessage?, theme?); the baseUrl override is honoured by debug builds only. ChatUser(customerName required, customerEmail?, customerId?, customerToken?). ready resolves once native configuration completes.

Authenticated customerslink

customerToken carries a chat identity token minted by your backend. When set it is the authoritative identity - the server derives name, email and customer id from its signed claims - so nothing else is needed:

await chat.setUserToken(tokenFromYourBackend);

customerId without a token is recorded for agent context only and is not treated as identity. See Authentication and identity.

Local themelink

NewinstanceChatConfig(
  apiKey: 'sk_live_abc123',
  theme: ChatThemeOverride(mode: 'dark', sentBubble: '#16A34A'),
);

Every ChatThemeOverride field is optional and merged token by token, ranked below the merchant's dashboard theme and above the built-in palette. Unset tokens are omitted from the platform-channel payload entirely. Full rules in Theming.

API and eventslink

Methods: setUser, initialize, openChat, closeChat, sendMessage, retryMessage, attachFile(AttachmentInput(uri, name, mimeType)), destroy. Handoff, typing and attachment removal are driven by the native screen, not the Dart surface.

Streams: onMessageReceived, onMessageSent, onAgentTypingChanged, onConnectionStateChanged (NcConnectionState: idle, connecting, connected, disconnected, offline), onUnreadCountChanged, onError. ChatMessage carries seq, sentAt, senderName and totalMessages.

The error streamlink

onError is the channel for "why is my chat not working". Nothing on it reaches the chat interface, and it never carries the API key, the identity token, or customer data.

chat.onError.listen((NewinstanceChatError e) {
  if (e.code == NcErrorCode.invalidIdentityToken) {
    refreshChatToken();
  } else if (!e.recoverable) {
    reportToYourMonitoring(e.code, e.message);
  }
});

NewinstanceChatError carries code (from NcErrorCode, the vocabulary shared with every other chat SDK), the broad type (NcErrorType: network, validation, auth, system), a developer-facing message, and recoverable. code is null only when talking to a native SDK older than the release that introduced coded errors. The full code list is in Authentication and identity -> Diagnosing problems.

Gotchaslink

• AttachmentInput.uri is a file:// URI on iOS and content:// or file:// on Android.
• theme, customerToken and coded errors require 0.3.0 of this package and of the underlying native SDKs.
• Multiple NewinstanceChat instances reconfigure one native singleton; the last config wins.
• After destroy(), construct a new instance to chat again.