Make Your Page React to the Agent

This tutorial walks you through letting your agent make the web page around it do something. You give Atlas, Kirana Group's operations assistant, a page event: when someone in Kirana's project portal says "Show me KG-2041", Atlas sends an open_project event to the portal, and the portal opens that project's page while Atlas carries on talking. By the end, you have a working page event, a listener on your page, and you have watched the event arrive in the embed builder.

Before you start

• Your agent is embedded on a website, or you are about to embed it. See Embed Chat on Your Website.
• You, or a developer on your team, can add a few lines of JavaScript to that website. The agent sends the event; your page's own script decides what happens.
• You know how to test and publish changes. See Preview and Publish Changes.

How Page Events Work

A Custom API calls your server. A page event goes the other way round, to the page the chat is embedded in, in the visitor's browser:

1. The AI reads the visitor's message and decides, from your description, that it is time to send the event.
2. qlar sends the event to the page: the event name you chose, the parameters the AI filled in, and the metadata you picked. Nothing is called on a server.
3. The widget element on your page dispatches a qlarPageEvent, and your listener runs: it opens a page, fills in a form, scrolls to a product — whatever your code does.
4. The AI carries on the conversation. It is told the event was sent, not what your page did with it: the page sends nothing back.

Page events are offered to the agent only while its chat runs inside the qlar widget on a web page, in text chat and in voice calls alike. On WhatsApp, Instagram or the standalone chat there is no page to send them to, so the agent does not see them there.

Scenario Used in This Tutorial

Kirana's project portal lists every project on its own page, at /projects/<code>. Atlas is embedded in the portal as a floating chat. The goal: when someone asks Atlas to show a project, the portal opens that project's page, without anyone leaving the conversation.

Step 1: Add the Page Event

1. In the agent sidebar, open Tools → Page Events.
2. Click Add page event. The New Page Event panel opens.
3. Fill in Basic Information:

4. Under Parameters, click Add New Property and fill in:

5. Leave Metadata as it is for now (see Choose the Metadata).
6. Click Add Page Event, then Save all changes and confirm.

To pause a page event later without losing it, turn off the switch on its row and save. The agent stops sending it until you turn it back on.

Note: qlar checks every value the AI fills in against the parameters you defined before the event leaves: a missing required parameter, a wrong type, or a value outside the enum is refused, and the AI is asked to try again. Parameters you did not define are dropped, unless you allow additional properties.

Step 2: Listen on Your Page

Add a listener for qlarPageEvent to the widget element. It receives every page event the agent sends:

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

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

    if (name === "open_project") {
      // Check the value like anything a visitor types before you use it.
      if (/^KG-\d{4}$/.test(parameters.projectCode)) {
        window.location.href = `/projects/${parameters.projectCode}`;
      }
    }
  });
</script>

The event bubbles, so a listener on document works too. On a page with more than one widget, event.detail.agentId says which one sent it.

What event.detail holds

In React

Attach the listener to the element through a 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>;
}

The embed builder adds a starting listener like these to the HTML page and the React component it generates, for every agent that has page events.

Step 3: Try It in the Embed Builder

You do not need your website to see the event work.

1. Open Channels → Embed and click Open builder.
2. Under the preview, the Page events panel lists the event names the agent can send.
3. Click Start, and ask the agent: Show me KG-2041.
4. The event appears in the Page events panel exactly as your page would receive it: open_project, with "projectCode": "KG-2041" and the metadata.

The builder runs your draft agent, so a page event you have saved but not yet published already works there. Publish the agent before you rely on it on your website. On a phone, the panel is the Events tab in the bottom bar.

Choose the Metadata

Metadata tells your page about the conversation the event came from. qlar fills in the values, never the AI, so they cannot be talked into something else.

Important: A page event lands in JavaScript on your web page, and every script on that page can read it, including analytics, tag managers and ads. That is why a page event offers less than a Custom API's Send Metadata: organization and owner IDs, permissions, file links and messenger accounts are never sent to a page. User ID and User email are personal data: turn them on only if your page needs them, and remember they are never sent while the conversation is in privacy mode.

Keep It Safe

• Treat parameters as visitor input. The AI fills them in from the conversation, and a visitor can steer the conversation. Check every value before you use it, as the example above does, and never build HTML from it unescaped.
• Do not use a page event as proof of anything. It says what the AI decided, not who the visitor is or that an action is allowed. For anything that changes data or costs money, let your page ask your own backend, which checks the visitor's session. If your agent needs to do something on your server, use a Custom API instead.
• Expect duplicates and gaps. Use id to ignore an event you have already handled. An event that arrives while your page is not listening (for example during a navigation) is not sent again, and reopening a conversation does not replay old events.

Troubleshooting

What's Next

• Field-by-field reference: Page Events
• Call your own server from the agent: Connect Your API
• Every widget attribute: Embed Chat on Your Website