Membuat Halaman Merespons Agent

Tutorial ini memandu Anda membuat agent bisa menggerakkan halaman web di sekitarnya. Anda memberi Atlas, asisten operasional Kirana Group, sebuah page event: saat seseorang di portal proyek Kirana berkata "Tampilkan KG-2041", Atlas mengirim event open_project ke portal, lalu portal membuka halaman proyek tersebut sementara Atlas tetap melanjutkan percakapan. Di akhir tutorial, Anda punya page event yang berfungsi, listener di halaman Anda, dan sudah melihat event itu tiba di embed builder.

Sebelum mulai

• Agent Anda sudah di-embed di website, atau akan segera di-embed. Lihat Embed Chat ke Website.
• Anda, atau developer di tim Anda, bisa menambahkan beberapa baris JavaScript ke website tersebut. Agent yang mengirim event; script halaman Anda sendiri yang menentukan apa yang terjadi.
• Anda sudah tahu cara menguji dan mem-publish perubahan. Lihat Preview dan Publish Perubahan.

Cara Kerja Page Event

Custom API memanggil server Anda. Page event berjalan ke arah sebaliknya, ke halaman tempat chat di-embed, di browser pengunjung:

1. AI membaca pesan pengunjung dan, berdasarkan deskripsi Anda, memutuskan bahwa sudah waktunya mengirim event.
2. qlar mengirim event ke halaman: nama event yang Anda pilih, parameter yang diisi AI, dan metadata yang Anda pilih. Tidak ada server yang dipanggil.
3. Elemen widget di halaman Anda men-dispatch qlarPageEvent, lalu listener Anda berjalan: membuka halaman, mengisi form, menggulir ke produk — apa pun yang dilakukan kode Anda.
4. AI melanjutkan percakapan. AI diberi tahu bahwa event sudah terkirim, bukan apa yang dilakukan halaman Anda: halaman tidak mengirim apa pun kembali.

Page event hanya ditawarkan ke agent selama chat-nya berjalan di dalam widget qlar pada sebuah halaman web, baik di chat teks maupun panggilan suara. Di WhatsApp, Instagram, atau chat standalone tidak ada halaman tujuan, jadi agent tidak melihat page event di sana.

Skenario yang Dipakai dalam Tutorial Ini

Portal proyek Kirana menampilkan setiap proyek di halamannya sendiri, di /projects/<kode>. Atlas di-embed di portal sebagai chat floating. Tujuannya: saat seseorang meminta Atlas menampilkan sebuah proyek, portal membuka halaman proyek tersebut tanpa ada yang perlu meninggalkan percakapan.

Langkah 1: Tambahkan Page Event

1. Di sidebar agent, buka Tools → Page Events.
2. Klik Add page event. Panel New Page Event terbuka.
3. Isi Basic Information:

4. Di Parameters, klik Add New Property lalu isi:

5. Biarkan Metadata apa adanya dulu (lihat Memilih Metadata).
6. Klik Add Page Event, lalu Save all changes dan konfirmasi.

Untuk menghentikan sementara sebuah page event tanpa kehilangannya, matikan switch di barisnya lalu simpan. Agent berhenti mengirimnya sampai Anda menyalakannya lagi.

Catatan: qlar memeriksa setiap nilai yang diisi AI terhadap parameter yang Anda definisikan sebelum event dikirim: parameter wajib yang hilang, tipe yang salah, atau nilai di luar enum ditolak, dan AI diminta mencoba lagi. Parameter yang tidak Anda definisikan dibuang, kecuali Anda mengizinkan additional properties.

Langkah 2: Pasang Listener di Halaman Anda

Tambahkan listener untuk qlarPageEvent ke elemen widget. Listener ini menerima setiap page event yang dikirim agent:

<script type="module">
  const atlas = document.querySelector("qlar-component");

  atlas.addEventListener("qlarPageEvent", (event) => {
    const { name, parameters, metadata } = event.detail;

    if (name === "open_project") {
      // Periksa nilainya seperti apa pun yang diketik pengunjung sebelum dipakai.
      if (/^KG-\d{4}$/.test(parameters.projectCode)) {
        window.location.href = `/projects/${parameters.projectCode}`;
      }
    }
  });
</script>

Event ini bubble, jadi listener di document juga berfungsi. Di halaman dengan lebih dari satu widget, event.detail.agentId menunjukkan widget mana yang mengirimnya.

Isi event.detail

Di React

Pasang listener ke elemen melalui ref:

import React, { useEffect, useRef } from "react";

export default function AtlasChat() {
  const chatRef = useRef<HTMLElement>(null);

  useEffect(() => {
    const element = chatRef.current;
    if (!element) return undefined;

    const handlePageEvent = (event: Event) => {
      const { name, parameters } = (event as CustomEvent).detail;
      if (name === "open_project") openProject(String(parameters.projectCode));
    };

    element.addEventListener("qlarPageEvent", handlePageEvent);
    return () => element.removeEventListener("qlarPageEvent", handlePageEvent);
  }, []);

  return <qlar-component ref={chatRef} data-agent-id="YOUR-AGENT-ID" data-mode="floating"></qlar-component>;
}

Embed builder menambahkan listener awal seperti ini ke halaman HTML dan komponen React yang dibuatnya, untuk setiap agent yang punya page event.

Langkah 3: Coba di Embed Builder

Anda tidak perlu website sendiri untuk melihat event bekerja.

1. Buka Channels → Embed lalu klik Open builder.
2. Di bawah preview, panel Page events menampilkan nama event yang bisa dikirim agent.
3. Klik Start, lalu tanyakan ke agent: Tampilkan KG-2041.
4. Event muncul di panel Page events persis seperti yang akan diterima halaman Anda: open_project, dengan "projectCode": "KG-2041" beserta metadata-nya.

Builder menjalankan agent draft, jadi page event yang sudah disimpan tapi belum di-publish sudah berfungsi di sana. Publish agent sebelum mengandalkannya di website Anda. Di ponsel, panel ini adalah tab Events di bilah bawah.

Memilih Metadata

Metadata memberi tahu halaman Anda tentang percakapan asal event. qlar yang mengisi nilainya, bukan AI, sehingga nilainya tidak bisa diarahkan lewat percakapan.

Penting: Page event diterima oleh JavaScript di halaman web Anda, dan setiap script di halaman itu bisa membacanya, termasuk analytics, tag manager, dan iklan. Karena itu page event menawarkan lebih sedikit dibanding Send Metadata pada Custom API: ID organisasi dan owner, permission, link file, dan akun messenger tidak pernah dikirim ke halaman. User ID dan User email adalah data pribadi: aktifkan hanya jika halaman Anda membutuhkannya, dan ingat keduanya tidak pernah dikirim selama percakapan dalam privacy mode.

Menjaga Keamanan

• Perlakukan parameter sebagai input pengunjung. AI mengisinya dari percakapan, dan pengunjung bisa mengarahkan percakapan. Periksa setiap nilai sebelum dipakai, seperti contoh di atas, dan jangan pernah menyusun HTML darinya tanpa escape.
• Jangan jadikan page event sebagai bukti apa pun. Event hanya menyatakan apa yang diputuskan AI, bukan siapa pengunjungnya atau bahwa suatu aksi diizinkan. Untuk apa pun yang mengubah data atau menimbulkan biaya, biarkan halaman Anda bertanya ke backend Anda sendiri, yang memeriksa sesi pengunjung. Jika agent perlu melakukan sesuatu di server Anda, gunakan Custom API.
• Siapkan diri untuk duplikat dan event yang terlewat. Gunakan id untuk mengabaikan event yang sudah ditangani. Event yang tiba saat halaman Anda tidak mendengarkan (misalnya saat berpindah halaman) tidak dikirim ulang, dan membuka kembali percakapan tidak memutar ulang event lama.

Pemecahan Masalah

Selanjutnya

• Referensi field demi field: Page Events
• Memanggil server Anda dari agent: Menghubungkan API Anda
• Semua atribut widget: Embed Chat ke Website