1. Apa itu Prefill Chat?

Prefill Chat adalah fitur click-to-chat yang membuka Livechat sekaligus membawa konteks dari layar tempat pengguna memulai percakapan. Konteks dapat berupa teks, URL gambar, atau kombinasi keduanya.

Contohnya, ketika pengguna menekan tombol “Tanya produk ini”, pesan pertama dapat langsung memuat nama produk, SKU, harga, pertanyaan awal, dan gambar produk. Agent menerima konteks yang sama dengan yang sedang dilihat pengguna sehingga percakapan dapat dimulai tanpa pertanyaan klarifikasi berulang.

Prefill Chat bukan pesan otomatis dari agent dan bukan pengganti formulir pra-chat. Pesan prefill mewakili pesan pengunjung yang dipicu oleh tindakan pengguna di aplikasi.

2. Manfaat utama

• Mengurangi pertanyaan klarifikasi dari agent.

• Mempercepat waktu menuju jawaban yang relevan.

• Menjaga konteks saat pengguna berpindah dari katalog atau detail produk ke percakapan.

• Membuat tombol call-to-action lebih spesifik daripada sekadar “Buka chat”.

• Mendukung pengalaman konsultatif karena pengguna dapat meninjau atau mengedit pesan sebelum mengirim.

3. Kapan Prefill Chat digunakan?

Prefill Chat cocok digunakan ketika layar aplikasi memiliki objek atau konteks yang jelas, antara lain:

• Katalog dan detail produk: nama produk, SKU, varian, harga, atau URL gambar.

• Paket layanan: nama paket, tier, durasi, atau kebutuhan konsultasi.

• Pesanan dan transaksi: nomor referensi yang aman dibagikan, status, atau jenis bantuan.

• Artikel bantuan: judul topik atau langkah yang sedang dibaca.

• Campaign dan landing page: nama program, promo, atau sumber campaign.

Gunakan prefill hanya untuk konteks yang membantu agent memahami maksud pengguna. Jangan memasukkan secret, token akses, data pembayaran, atau data pribadi yang tidak diperlukan.

4. Cara pakai cepat

Untuk membuka chat dengan pesan awal, buat BarantumPrefill lalu berikan melalui property prefill pada BarantumWidgetConfig:

final config = BarantumWidgetConfig(

  livechat: const BarantumLivechatConfig(

    baseUrl: 'https://livechat.barantum.com',

    inboxIdentifier: 'INBOX_IDENTIFIER_ANDA',

    appId: 'my-flutter-app',

  ),

  prefill: const BarantumPrefill(

    text: 'Halo, saya ingin menanyakan Kursi Aurora (SKU AUR-001).',

    image: 'https://cdn.example.com/products/kursi-aurora.jpg',

    autoSend: true,

  ),

);

Tampilkan konfigurasi tersebut menggunakan BarantumWidget:

BarantumWidget(

  config: config,

  onCloseRequested: () => Navigator.of(context).pop(),

);

Dengan pola ini, SDK akan menunggu halaman widget, koneksi chat, dan formulir pra-chat—jika aktif—sebelum memproses prefill.

5. Property dan method yang digunakan

5.1 BarantumPrefill

BarantumPrefill adalah model payload konteks yang akan diteruskan ke Livechat.

const BarantumPrefill({

  String? text,

  String? image,

  bool autoSend = true,

});

Property text

• Tipe: String?.

• Opsional, tetapi minimal text atau image harus valid.

• Spasi awal dan akhir dihapus oleh widget.

• Panjang maksimum 2.000 karakter; karakter setelah batas akan dipotong.

Property image

• Tipe: String?.

• Harus berupa URL absolut HTTP atau HTTPS.

• Ukuran file maksimum 40 MiB.

• Host gambar harus dapat diakses WebView dan mengizinkan CORS.

• URL relatif, data:, javascript:, dan skema non-HTTP(S) akan diabaikan.

Property autoSend

• Tipe: bool.

• Default: true.

• true mengirim payload setelah chat siap.

• false hanya menyalin text ke composer agar pengguna dapat meninjau atau mengubahnya.

• image tidak dimasukkan ke composer ketika autoSend bernilai false.

5.2 BarantumWidgetConfig.prefill

Property prefill pada BarantumWidgetConfig digunakan untuk initial prefill, yaitu payload yang diproses saat layar chat pertama kali dibuka.

BarantumWidgetConfig(

  livechat: livechatConfig,

  visitor: visitor,

  prefill: BarantumPrefill(...),

);

Gunakan initial prefill ketika chat dibuka dari suatu produk, layanan, pesanan, atau objek tertentu.

5.3 BarantumWidgetController.prefill()

Method prefill() digunakan untuk mengirim konteks baru ketika BarantumWidget sudah dibuat dan tetap berada di layar.

final controller = BarantumWidgetController();

await controller.prefill(

  const BarantumPrefill(

    text: 'Apakah produk ini masih tersedia?',

    autoSend: true,

  ),

);

Method menerima satu BarantumPrefill dan mengembalikan Future<void>. Controller boleh menerima payload sebelum halaman WebView siap; SDK akan menahannya sementara. Namun, controller harus sudah terpasang pada BarantumWidget. Jika belum, method melempar StateError “BarantumWidgetController belum terpasang”.

5.4 BarantumWidget.controller dan onReady

Berikan instance controller yang sama ke BarantumWidget. Callback onReady menandakan antarmuka chat sudah tersambung dan siap digunakan.

BarantumWidget(

  controller: controller,

  config: config,

  onReady: () {

    setState(() => isChatReady = true);

  },

);

Disarankan mengaktifkan tombol runtime prefill setelah onReady agar pengguna tidak menekan tindakan chat sebelum antarmuka siap.

6. Cara kerja dan siklus hidup

1) Pengguna menekan tombol click-to-chat pada katalog atau detail produk.

2) Aplikasi membuat BarantumWidgetConfig dengan initial prefill, atau memanggil BarantumWidgetController.prefill() untuk runtime prefill.

3) SDK memvalidasi halaman widget dan meneruskan payload ke Livechat.

4) Jika WebView belum siap, runtime payload disimpan sementara sampai halaman widget selesai dimuat.

5) Widget memvalidasi text, image, dan autoSend. Jika pra-chat aktif, pengiriman menunggu proses pra-chat selesai.

6) Payload diproses sesuai nilai autoSend.

7) Payload yang sudah diproses dihapus dari antrean agar tidak terkirim ulang hanya karena layar ditutup atau dibuka kembali.

7. Perilaku autoSend

Saat autoSend bernilai true

• Teks saja dikirim sebagai pesan teks.

• Gambar valid dikirim sebagai lampiran.

• Jika text dan image tersedia, text menjadi caption lampiran.

• Jika gambar gagal diunduh, widget otomatis mengirim text dan URL gambar sebagai pesan fallback.

• Jika download berhasil tetapi upload lampiran gagal, fallback text + URL gambar juga dikirim otomatis agar tombol Kirim otomatis tidak terlihat diam.

Saat autoSend bernilai false

• Hanya text yang disalin ke composer.

• Pengguna dapat meninjau atau mengubah teks sebelum menekan tombol kirim.

• image tidak dimasukkan ke composer pada mode ini.

await controller.prefill(

  const BarantumPrefill(

    text: 'Saya ingin menambahkan detail pertanyaan terlebih dahulu.',

    autoSend: false,

  ),

);

8. Pemrosesan gambar dan fallback

Ketika image diberikan bersama autoSend: true, widget mencoba mengambil file dari URL tersebut dan mengirimkannya sebagai lampiran. Gunakan URL HTTPS publik yang stabil, memiliki Content-Type gambar yang benar, berukuran maksimal 40 MiB, dan mengizinkan akses CORS dari origin widget.

Jika lampiran tidak dapat dibuat, SDK mempertahankan konteks melalui text dan/atau URL gambar sebagai fallback. Mekanisme fallback bukan pengganti konfigurasi host gambar yang benar.

9. Tutorial lengkap: click-to-chat dari katalog produk

Tutorial berikut membuat katalog sederhana. Pengguna memilih produk, kemudian membuka Livechat dengan initial prefill. Halaman chat juga menyediakan runtime prefill melalui controller.

9.1 Prasyarat

• Flutter 3.10 atau lebih baru.

• Dart 3.0 atau lebih baru.

• Project Flutter untuk Android dan/atau iOS.

• Package barantum_widget dari SDK Barantum.

• Inbox Livechat Barantum beserta Inbox Identifier untuk pengujian nyata.

• Koneksi internet pada perangkat atau emulator.

9.2 Pasang package Flutter

Tambahkan package lokal pada pubspec.yaml aplikasi:

dependencies:

  flutter:

    sdk: flutter

  barantum_widget:

    path: libs/sdk-services/packages/flutter

Jalankan dependency resolution:

flutter pub get

Import SDK pada file Dart yang menampilkan chat:

import 'package:barantum_widget/barantum_widget.dart';

9.3 Konfigurasi Android

Tambahkan permission internet pada android/app/src/main/AndroidManifest.xml, di luar elemen <application>:

<uses-permission android:name="android.permission.INTERNET" />

Untuk iOS tidak diperlukan konfigurasi tambahan jika seluruh endpoint menggunakan HTTPS.

9.4 Buat model produk

class Product {

  const Product({

    required this.name,

    required this.sku,

    required this.price,

    required this.imageUrl,

  });

  final String name;

  final String sku;

  final String price;

  final String imageUrl;

}

9.5 Buat tombol dari katalog ke chat

Pada tombol produk, bentuk initial prefill lalu buka ProductChatPage:

void openProductChat(BuildContext context, Product product) {

  Navigator.of(context).push(

    MaterialPageRoute(

      builder: (_) => ProductChatPage(

        product: product,

        initialPrefill: BarantumPrefill(

          text: 'Halo, saya ingin menanyakan ${product.name} '

              '(SKU ${product.sku}, harga ${product.price}).',

          image: product.imageUrl,

          autoSend: true,

        ),

      ),

    ),

  );

}

Untuk memberi kesempatan pengguna mengedit pesan, gunakan payload yang sama dengan autoSend: false. Pada mode tersebut image tidak akan dimasukkan ke composer.

9.6 Implementasikan halaman chat

class ProductChatPage extends StatefulWidget {

  const ProductChatPage({

    super.key,

    required this.product,

    required this.initialPrefill,

  });

  final Product product;

  final BarantumPrefill initialPrefill;

  @override

  State<ProductChatPage> createState() => _ProductChatPageState();

}

class _ProductChatPageState extends State<ProductChatPage> {

  final _controller = BarantumWidgetController();

  bool _ready = false;

  static const _inboxIdentifier = 'INBOX_IDENTIFIER_ANDA';

  @override

  Widget build(BuildContext context) {

    final config = BarantumWidgetConfig(

      livechat: const BarantumLivechatConfig(

        baseUrl: 'https://livechat.barantum.com',

        inboxIdentifier: _inboxIdentifier,

        appId: 'APP_ID_ANDA',

      ),

      visitor: const BarantumVisitor(

        externalId: 'user-42',

        name: 'Budi',

      ),

      prefill: widget.initialPrefill,

    );

    return Scaffold(

      appBar: AppBar(

        title: Text(widget.product.name),

        actions: [

          IconButton(

            tooltip: 'Kirim runtime prefill',

            onPressed: !_ready

                ? null

                : () => _controller.prefill(

                      BarantumPrefill(

                        text: 'Apakah ${widget.product.name} masih tersedia?',

                        image: widget.product.imageUrl,

                        autoSend: true,

                      ),

                    ),

            icon: const Icon(Icons.send),

          ),

        ],

      ),

      body: BarantumWidget(

        controller: _controller,

        config: config,

        onReady: () => setState(() => _ready = true),

        onCloseRequested: () => Navigator.of(context).pop(),

        onError: (message) {

          ScaffoldMessenger.of(context).showSnackBar(

            SnackBar(content: Text(message)),

          );

        },

      ),

    );

  }

}

Pada contoh tersebut, BarantumWidgetConfig selalu memakai koneksi inbox asli. Isi Inbox Identifier dan App ID sesuai konfigurasi Livechat Anda.

9.7 Menjalankan project contoh

Project siap uji tersedia pada folder:

examples/flutter-prefill-sample

Jalankan project yang sudah dikonfigurasi ke inbox asli:

cd examples/flutter-prefill-sample

flutter pub get

flutter run

HMAC secret sample sudah didefinisikan sebagai konstanta _hmacSecret di lib/main.dart. Aplikasi otomatis membuat identifierHash di device menggunakan HMAC-SHA256 setiap kali layar chat dibuka; tidak ada dialog input atau backend signing.

Project contoh menyediakan initial prefill text + image, autoSend true dan false, runtime prefill, serta koneksi langsung ke inbox asli. Config visitor dan HMAC secret memakai nilai yang didefinisikan di source sample, sedangkan identifierHash tetap digenerate di device saat runtime; tidak ada mock transport atau backend signing tambahan.

10. Menyusun isi prefill yang baik

Disarankan:

• Cantumkan nama objek yang sedang dilihat.

• Sertakan identifier yang berguna bagi agent, misalnya SKU atau nomor referensi yang aman.

• Gunakan kalimat dari sudut pandang pengguna.

• Pertahankan isi tetap singkat dan mudah dipindai.

Contoh yang baik:

Halo, saya ingin menanyakan Kursi Aurora (SKU AUR-001). Apakah warna hitam masih tersedia?

Kurang informatif:

Saya mau tanya ini.

Hindari:

• Secret atau token akses.

• Data kartu pembayaran.

• Data pribadi yang tidak diperlukan untuk percakapan.

• Payload teknis mentah yang sulit dipahami agent.

11. Troubleshooting

Controller melempar “belum terpasang”

Pastikan instance controller yang sama diberikan ke BarantumWidget dan jangan memanggil prefill sebelum BarantumWidget dibuat.

Prefill runtime tidak muncul

Pastikan text atau image valid, controller masih terpasang, dan layar chat belum di-dispose. Gunakan onReady untuk mengaktifkan tombol interaksi pengguna.

Gambar berubah menjadi URL teks

Periksa status HTTP, Content-Type, ukuran maksimum 40 MiB, HTTPS, dan header CORS host gambar. Jika download atau upload lampiran gagal, widget mengirim text + URL gambar sebagai fallback otomatis.

Pesan hanya muncul di composer

Pastikan autoSend bernilai true. Nilai false memang hanya mengisi composer.

autoSend false tidak menampilkan gambar

Sesuai desain, mode ini hanya mengisi text ke composer.

Widget kosong atau terus loading

Periksa koneksi internet, widgetUrl, Inbox Identifier, dan permission Android.

Pesan terkirim dua kali

Pastikan handler tombol hanya memanggil prefill() satu kali dan tidak didaftarkan ulang saat rebuild.

12. Checklist pengujian

1) Pilih produk dan tekan tombol Kirim otomatis.

2) Pastikan chat terbuka dan pesan visitor hanya muncul satu kali.

3) Pastikan text menjadi caption jika image berhasil diunduh.

4) Kembali ke katalog, pilih Edit dahulu, lalu pastikan composer terisi tanpa pesan terkirim.

5) Setelah onReady, uji runtime prefill melalui controller.

6) Uji dengan preChat: true; prefill harus diproses setelah formulir selesai.

7) Tutup dan buka kembali layar; prefill sebelumnya tidak boleh terkirim ulang.

8) Uji URL gambar yang gagal untuk memastikan fallback tetap membawa konteks.

13. Keamanan untuk production

Pada sample debug, identifierHash dibuat langsung di device dengan rumus HMAC-SHA256(secret, externalId), sama seperti generateIdentifierHmac() pada referensi web. HMAC secret didefinisikan sebagai konstanta _hmacSecret di main.dart sesuai kebutuhan pengujian. HMAC-SHA256 bersifat deterministik: externalId dan secret yang sama menghasilkan hash yang sama; jangan membuat hash acak setiap kali chat dibuka.

Aplikasi menghitung hash sebelum membuka layar chat lalu meneruskannya ke BarantumLivechatConfig:

BarantumLivechatConfig(

  baseUrl: 'https://livechat.barantum.com',

  inboxIdentifier: 'INBOX_IDENTIFIER_ANDA',

  identifierHash: identifierHash,

  appId: 'my-flutter-app',

);

Agar history dipulihkan, pertahankan externalId, Inbox Identifier, appId, dan HMAC secret yang sama sehingga generator menghasilkan identifierHash valid yang sama. Conversation yang sudah resolved dapat membuka room aktif baru, tetapi tetap tersedia di daftar riwayat. Secret yang didefinisikan di source sample hanya untuk pengujian lokal/debug; jangan gunakan pola ini pada APK atau IPA production karena binary aplikasi dapat diekstrak.

Validasi kembali bahwa text dan image tidak memuat data sensitif sebelum membuat BarantumPrefill.