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
- In Helpr, create an API inbox. Copy its inbox identifier, and, to identify signed-in users, its HMAC token (Settings โ Inboxes โ the inbox โ Configuration).
- Add the package:
flutter pub add helpr_chat
- Create one
HelprSupportfor 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.countis 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.
- 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).
- 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.
- 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: myThemetoHelprSupport: 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,RoomChannelwith 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 useswss://);allowInsecure: trueallowshttp://for local development only. - Requests time out after 20 seconds; errors, including an unexpected answer such as a captive Wi-Fi page, are
HelprApiExceptionwith 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 overhttps://, andallowInsecureis 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 callsclient.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
Libraries
- helpr_chat
- Helpr support chat for Flutter apps.