Skip to main content

Search documentation

Search Fiko's documentation

Flutter SDK

Add Fiko live chat to your Flutter app on Android and iOS. The fiko_chat package shows your existing Fiko widget inside your app, so conversations arrive in the same inbox as chats from your website.

How It Works

The SDK opens your Fiko widget full-screen in a web view. Everything you set up in the dashboard carries over: colors, welcome messages, forms, languages, AI replies, and team assignment. You don't need to host any web page yourself.

  • One line of code opens the chat full-screen and closes it when the visitor is done
  • Conversations and history are kept between app launches
  • Links in messages open in the phone's browser
  • Visitors can attach files on Android and iOS

Requirements

  • Flutter 3.27 or later
  • Android 5.0 (API 21) or later, iOS 12 or later
  • A Fiko widget channel. Create one under Settings → Channels → Fiko Widgets
  • The widget's channel id. It's the value of window.__chat.channelId in the install code on the widget's installation page

Step 1: Install the Package

Add fiko_chat to your app's pubspec.yaml:

dependencies:
  fiko_chat:
    git:
      url: https://gitlab.com/thienphuc718/fiko-flutter-sdk.git
      ref: v0.1.0

Then run flutter pub get.

Step 2: Platform Setup

Android

Make sure your app can use the internet. In android/app/src/main/AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.INTERNET"/>
    <application ...>

iOS

No setup needed.

Step 3: Open the Chat

Call FikoChat.open from any button. It opens the chat full-screen and closes that screen when the visitor closes the chat or presses back.

import 'package:fiko_chat/fiko_chat.dart';

FilledButton(
  onPressed: () => FikoChat.open(
    context,
    config: FikoChatConfig(channelId: 'your-channel-id'),
  ),
  child: const Text('Chat with us'),
)

Test it: run your app, open the chat, and send a message. It appears in your Fiko inbox like any website conversation.

Show the Chat in Your Own Screen

To control the layout yourself, for example inside a tab or under your own app bar, use FikoChatView instead. Give it the space you want the chat to fill.

final chat = FikoChatController();

FikoChatView(
  config: FikoChatConfig(channelId: 'your-channel-id'),
  controller: chat,
  onReady: () => debugPrint('Chat is open'),
  onClosed: () => Navigator.of(context).pop(),
  onError: (error) => debugPrint(error.toString()),
)

A FikoChatController lets your code open and close the chat panel:

// Load the widget without opening the panel, then open it later.
FikoChatView(
  config: FikoChatConfig(channelId: 'your-channel-id', openOnLoad: false),
  controller: chat,
)

await chat.show();
await chat.hide();
await chat.toggle();

Visitor Details and Language

If your app already knows who the user is, pass their name and email so your team sees them in the conversation instead of an anonymous visitor. Set language to show the widget in the user's language. Without it, the widget uses the channel's default language from your dashboard, not the phone's language.

FikoChat.open(
  context,
  config: FikoChatConfig(
    channelId: 'your-channel-id',
    language: 'vi',
    visitor: FikoVisitorInfo(name: user.fullName, email: user.email),
  ),
);

// Or, on a FikoChatView that is already showing (for example after login):
await chat.setVisitorInfo(FikoVisitorInfo(name: user.fullName, email: user.email));

language uses the same codes as the website snippet. See Sync the Widget Language for the supported languages and how translations are chosen.

Allowed Domains

Inside your app the chat runs under the address https://fiko-chat-sdk.local. If your widget's allowed domains list (in the widget's security settings) is empty, every address is accepted and you don't need to do anything.

If you restrict the widget to certain domains, do one of the following:

  • Add fiko-chat-sdk.local to the widget's allowed domains, or
  • Pass an origin whose host is already on the list, as shown below
FikoChatConfig(
  channelId: 'your-channel-id',
  origin: Uri.parse('https://app.example.com'),
)

Keep the origin the same between releases. The visitor's conversation is saved per origin, so changing it starts every user on a new, empty conversation.

API Reference

FikoChatConfig

FieldTypeDefaultDescription
channelIdStringrequiredWidget channel id from the Fiko dashboard.
environmentFikoEnvironmentproductionproduction or staging.
originUrihttps://fiko-chat-sdk.localOrigin the chat page runs under. Its host must pass the channel's allowed domains.
languageString?noneWidget language code, e.g. 'vi'. Same codes as the website snippet.
visitorFikoVisitorInfo?noneVisitor name and email to attach to the conversation.
openOnLoadbooltrueOpen the chat panel as soon as the widget loads.
readyTimeoutDuration20 secondsHow long to wait before reporting a timeout error.

FikoChatView

ParameterTypeDescription
configFikoChatConfigChannel and widget settings.
controllerFikoChatController?Lets your code open, close, and update the chat.
onReadyVoidCallback?Called once the chat is usable.
onClosedVoidCallback?Called when the visitor closes the chat. When set, the loading and error screens also show a Close button.
onErrorValueChanged<FikoChatError>?Called when the chat cannot be shown.
loadingWidget?Replaces the default loading spinner.

FikoChatController

MethodDescription
show()Opens the chat panel.
hide()Closes the chat panel.
toggle()Opens or closes the chat panel.
setVisitorInfo(FikoVisitorInfo)Attaches a name and email to the conversation.

FikoChatErrorType

ValueMeaning
pageLoadFailedThe chat page or the widget script could not load, usually because the device is offline.
timeoutThe chat did not open in time. Check the channel id, that the widget is enabled, and the channel's allowed domains.

Troubleshooting

"Chat could not be loaded"

  • Channel id: copy it again from the widget's installation page
  • Widget enabled: check the widget is turned on and its visibility isn't set to always hide
  • Allowed domains: see the Allowed Domains section above
  • Network: the device must reach s3-fiko.s3.us-east-1.amazonaws.com and Fiko's servers

Users see an empty conversation after an update

The origin changed between versions. Set it back to the previous value.

A link opened the browser instead of staying in the app

This is intended: links in chat messages open in the phone's browser so visitors don't lose the conversation.

Next Steps

Customize Your Widget

Colors, texts, and forms you change in the dashboard apply to your app too.

Customize

Advanced Configuration

Set up forms, multi-language support, and security settings.

Configure
Flutter SDK — Fiko Docs