Skip to main content

helpr_chat 0.2.0 copy "helpr_chat: ^0.2.0" to clipboard
helpr_chat: ^0.2.0 copied to clipboard

Helpr support chat for Flutter apps — conversations, live replies, wallet context and issue intake forms over Helpr's public client API.

helpr_chat #

Helpr support chat for Flutter apps. It talks to Helpr's public client API for an API inbox: conversations, live replies, wallet context and issue intake forms.

Setup #

  1. In Helpr, create an API inbox. Copy its inbox identifier, and, to identify signed-in users, its HMAC token (Settings → Inboxes → the inbox → Configuration).
  2. Add the package:
flutter pub add helpr_chat
  1. Create one HelprSupport for the app and put its ways in where customers look:
final support = HelprSupport(
  client: HelprClient(
    api: HelprApi(baseUrl: Uri.parse('https://support.example.com'), inboxIdentifier: 'YOUR_INBOX_IDENTIFIER'),
  ),
  identity: () => user == null
      ? null
      : HelprIdentity(
          identifier: user.id,
          identifierHash: user.helprHash,
          name: user.name,
          email: user.email,
          phoneNumber: user.phone,
        ),
)..start();

AppBar(actions: [HelprSupportIconButton(support: support)]); // top bar, with the unread badge
HelprSupportTile(support: support);                           // a "Help & support" row in Settings
HelprHelpLink(support: support, about: {'transaction': hash}); // "Need help?" where something failed

Without an identity the customer chats anonymously; the session is kept on the device.

Customer details #

HelprIdentity tells Helpr who the signed-in customer is. Your team sees these details on the contact, beside every conversation.

Field Required What it is
identifier Yes The user's id in your app.
identifierHash When the inbox enforces identity validation Proves the id came from your server (see below).
name No The customer's full name.
email No The customer's email address.
phoneNumber No The customer's phone number, with country code (e.g. +14155550123).

Identity: sign on your server, never in the app #

identifierHash is HMAC-SHA256(inbox HMAC token, identifier) as hex. Compute it on your server and send it to the app with the signed-in user. The HMAC token must never ship in the app.

OpenSSL::HMAC.hexdigest('sha256', ENV.fetch('HELPR_INBOX_HMAC_TOKEN'), user.id.to_s)
hmac.new(HELPR_INBOX_HMAC_TOKEN.encode(), str(user.id).encode(), hashlib.sha256).hexdigest()

When a user signs out of your app, call await chat.client.logout() so the next user starts a new session.

Support home and ways in #

HelprSupportIconButton and HelprSupportTile open the support home (support.open(context)). It looks like the website widget's home, in the inbox's colour:

  • a brand gradient header with the protocol's logo and name, who answers (the AI's avatar when an assistant is connected, and the team's), and "Hi Sam 👋" (or "Hi there 👋") over the welcome title and tagline;
  • Recent conversation, with "See all" when there are several; the inbox's topics; and Send us a message, with how fast replies come;
  • Home and Messages tabs at the bottom; Messages lists open, then resolved conversations, with New conversation.

HelprHelpLink (support.openChat(context, about: {...})) starts a new conversation. The about values (the screen, transaction or error) show to agents as the conversation's attributes, so nobody has to ask what happened. support.openChat(context, conversationId: id) opens one conversation, e.g. from a tapped notification, and support.openMessages(context) opens the full list. HelprSupport also takes strings, theme, pickAttachment and onOpenUrl, and passes them to every screen.

The controllers and screens below remain available for apps that build their own navigation.

Several conversations #

A customer can have several conversations. Show their Messages list (open ones first, then resolved, each with what it is about, the last reply and unread replies, and a New conversation button):

final list = HelprConversationsController(client: client, identity: identity);
await list.start();
Navigator.of(context).push(MaterialPageRoute(builder: (_) => HelprConversationsScreen(controller: list)));

Or open one conversation directly, e.g. from a tapped push notification:

final chat = HelprChatController(client: client, conversationId: HelprPush.conversationId(message.data));

HelprChatController(newConversation: true) starts a blank one; without either it opens the latest open conversation. list.unreadCount is the total for a badge. All screens share the client's one live connection.

Unread badge #

Show the customer's unread replies on your app's support button, kept current live:

final unread = HelprUnread(client: client)..start(); // once, at app start

HelprUnreadBadge(
  unread: unread,
  child: IconButton(icon: const Icon(Icons.support_agent), onPressed: openSupport),
)
  • It goes up when the team or the AI replies in a conversation that is not on screen, and back down once the customer reads it: the chat screen marks a conversation read while it is shown with the app in the foreground.
  • It refreshes when the app comes back to the foreground (replies that came by push) and resets on sign-out.
  • It only uses a session already on the device: an app user who never opened support shows 0 and is not added to Helpr's contacts. unread.count is the number, for your own badge.

The AI assistant and the team #

Connect an AI assistant to the API inbox (Captain → the assistant → Inboxes) and it answers in the app as on the website, from the same documents and FAQs:

  • Who answers — the header shows AI answers instantly · team on hand, Waiting for the team, You're chatting with the team or This conversation is resolved (chat.supportState).
  • The reply on its way — typing dots appear as soon as the AI starts, then its reply grows word by word (chat.replyTyping, chat.streamingReply); the finished message replaces it.
  • Talk to a person — while the AI answers, a Talk to a person button sits above the composer; chat.requestHuman() hands the conversation to the team, as the website widget does.
  • Rating — when the team resolves the conversation, a rating card asks Helpful / Not helpful (chat.rate(card, 5 or 1)).

The chat looks like the website widget's: a brand gradient header with who answers, grouped bubbles (the AI's marked with an AI pill), a rounded composer with a round send button, and a safety notice under it (HelprStrings(safetyNotice: '') hides it).

Live events arrive on HelprLive.messages (new and updated messages) and HelprLive.signals (HelprTyping, HelprStreaming, HelprStatusChanged).

Push notifications #

The customer gets a notification when your team or the AI replies, on Android and iOS, through your app's own Firebase project.

  1. In Firebase (the project your app already uses): for iOS, upload your APNs key (Project settings → Cloud Messaging). Then create a service account key (Project settings → Service accounts → Generate new private key).
  2. In Helpr: Settings → Inboxes → your API inbox → Configuration → Push notifications. Enter the Firebase project ID and paste the key JSON. The key is stored encrypted and never shown again.
  3. In the app (with firebase_messaging):
final messaging = FirebaseMessaging.instance;
await messaging.requestPermission();
final platform = Platform.isIOS ? HelprPushPlatform.ios : HelprPushPlatform.android;
final token = await messaging.getToken();
if (token != null) await chat.client.registerPush(token, platform: platform);
messaging.onTokenRefresh.listen((token) => chat.client.registerPush(token, platform: platform));

// Open the chat when the customer taps a Helpr notification.
FirebaseMessaging.onMessageOpenedApp.listen((message) {
  if (HelprPush.conversationId(message.data) != null) openSupportChat();
});

The token follows the customer: chat.client.logout() removes it, so the next person signed in on the phone never gets the previous customer's replies. Each notification shows who replied and the start of the reply; its data holds helpr_conversation_id. Tokens Firebase reports as gone are removed by Helpr.

Attachments #

Customers can send screenshots and files, and see the images and files the team sends. The SDK has no native picker of its own: pass one, so you keep the plugins your app already uses.

HelprChatScreen(
  controller: chat,
  // e.g. with image_picker; return null when the customer cancels.
  pickAttachment: () async {
    final photo = await ImagePicker().pickImage(source: ImageSource.gallery);
    if (photo == null) return null;
    return HelprFile(name: photo.name, bytes: await photo.readAsBytes(), mimeType: photo.mimeType ?? 'image/jpeg');
  },
  // Opens files the team sent (images open in the chat), e.g. with url_launcher.
  onOpenUrl: (url) => launchUrl(url, mode: LaunchMode.externalApplication),
);
  • The attach button appears only with pickAttachment; the composer's text is sent with the file.
  • A picked file shows at once and keeps Tap to retry if the upload fails; files over 40 MB (Helpr's default limit) are refused before uploading (HelprFileTooLarge).
  • Images show in the conversation and open full screen with zoom; other files show their name and size.
  • In code: chat.send('Here is the error', files: [file]).

Wallet context (web3 apps) #

Report the wallet your app connected; agents and Captain see it as reported, not verified (needs the account's web3_context feature):

await chat.reportWallet(Web3Context(chainId: 8453, address: wallet.address, walletName: 'MetaMask', expectedChainId: 8453));
await chat.reportWallet(null); // after a disconnect

// For wallet diagnosis, report what happened after the customer acted:
await chat.client.api.reportWalletEvent(chat.client.session!.sourceId,
    conversationId: chat.conversationId!, transactionHash: txHash);

Solana: Web3Context(solanaCluster: 'mainnet-beta', address: publicKey).

Intake forms #

With the account's issue_forms feature, the chat screen shows Report an issue, listing the forms enabled under Settings → Issue forms. Fields the form fills from the reported wallet may be left blank.

Appearance #

The chat screens style themselves from the inbox's App appearance in Helpr (Settings → Inboxes → your API inbox): brand colour, light / dark / follow the phone, and the welcome title and tagline shown on an empty chat, plus the inbox's avatar in the chat header. "Match a website widget" there copies your widget's look. Changes reach the app without an update.

  • The brand colour is used exactly; text on it is white or dark, whichever stays readable (3:1 contrast, as the website widget does).
  • Your app's fonts and shapes are kept. To use your own theme instead, pass theme: myTheme to HelprSupport: its primary colour becomes the brand colour and its brightness decides light or dark, on every screen.
  • helprTheme(appearance, platformBrightness: …) builds the same theme for your own screens.

Your own colours #

To match your app exactly, set any colour yourself with HelprColors: one set for light screens and one for dark. Anything you leave out keeps its default, so you can change one colour or all of them.

HelprSupport(
  client: client,
  colors: const HelprColors(
    brand: Color(0xFF0E7C66),
    headerGradient: LinearGradient(colors: [Color(0xFF0E7C66), Color(0xFF0A5C4C)]),
    page: Color(0xFFFFFBF5),
    customerBubble: Color(0xFF0E7C66),
    agentBubble: Color(0xFFF1EDE4),
  ),
  darkColors: const HelprColors(brand: Color(0xFF34D3A6), page: Color(0xFF101413)),
);
Colour What it paints
brand, onBrand Buttons, links and badges, and the text and icons on them and on the header.
headerGradient The header behind the greeting and the chat's title. Use one colour twice for a flat header.
customerBubble, onCustomerBubble The customer's own messages and their text.
agentBubble, onAgentBubble The team's and the AI's messages and their text.
page, card The screen background; cards, the message box and the bottom tabs.
outline, divider Card borders and the lines between rows.
text, textMuted, textFaint Titles and messages, secondary text, hints and timestamps.
chip Faint pills such as status and date labels.
ai, aiGradient, aiPill, onAiPill The AI's sparkle, its avatar, and the "AI" pill with its text.
online, error The online dot, and a message that was not sent.

colors is used on light screens and darkColors on dark ones. Light or dark comes from your theme when you pass one, otherwise from the inbox's setting in Helpr (which can follow the phone). The same options are on HelprChatScreen and HelprConversationsScreen.

Text and localisation #

All UI text lives in HelprStrings; pass your own values:

HelprChatScreen(controller: chat, strings: const HelprStrings(composerHint: 'Escribe un mensaje'));

How it behaves #

  • Sent messages show at once and carry an echo id, so a retry or a live echo never duplicates them; a message that did not reach Helpr shows Not sent · Tap to retry.
  • Live replies arrive over Helpr's websocket (/cable, RoomChannel with the contact's pubsub token) and reconnect with backoff (1 s, doubling to 30 s).
  • The session (contact source id and pubsub token) is stored with flutter_secure_storage. It is not reused for another identified user, and is recreated when Helpr no longer knows it.
  • The base URL must be https:// (the websocket then uses wss://); allowInsecure: true allows http:// for local development only.
  • Requests time out after 20 seconds; errors, including an unexpected answer such as a captive Wi-Fi page, are HelprApiException with a message safe to show to customers.
  • Live frames of the wrong shape are dropped; a refused subscription stops reconnecting.

Not included yet: voice notes and video playback in the chat (they arrive as files).

Go live #

  • ❌ The base URL is your production Helpr over https://, and allowInsecure is off in release builds.
  • ❌ The HMAC token is on your server only. Search the app's code for it to make sure.
  • ❌ Enforce user identity validation is on in the inbox configuration.
  • ❌ The production assistant is connected to the app's inbox, and its documents and FAQs are approved.
  • ❌ Your team is added to the inbox, and someone watches it during your support hours.
  • ❌ Push works on a real iPhone (with the APNs key uploaded) and on an Android phone.
  • ❌ Signing out of your app calls client.logout().
  • ❌ The privacy text for photos and camera is filled in on iOS, if you use attachments.

Troubleshooting #

Symptom Cause and fix
ArgumentError: baseUrl must use https The base URL uses http://. Use https://, or pass allowInsecure: kDebugMode for local development only.
"This chat is no longer available." The inbox identifier is wrong, or the inbox was deleted.
"HMAC failed" / signed-in user can't chat The hash was computed with a different token or id. Hash the exact identifier the app sends, with this inbox's HMAC token, as hex.
No AI answer, only "Waiting for the team" No assistant is connected to this inbox, or the team has taken the conversation over.
No push Check the project ID and key in Helpr, the APNs key in Firebase (iOS), that the customer allowed notifications, and that registerPush ran after support was opened.
Badge stays at 0 HelprUnread only counts for customers who have opened support on this device.
Android emulator can't reach a local Helpr Use http://10.0.2.2:3000 instead of localhost. Debug builds already allow cleartext traffic.

Development #

flutter pub get
flutter analyze
flutter test
0
likes
150
points
--
downloads

Documentation

API reference

Publisher

unverified uploader

Weekly Downloads

Helpr support chat for Flutter apps — conversations, live replies, wallet context and issue intake forms over Helpr's public client API.

Homepage

License

MIT (license)

Dependencies

flutter, flutter_secure_storage, http, http_parser, web_socket_channel

More

Packages that depend on helpr_chat