Page Events
Open in CMSThe Page Events screen defines events your agent can send to the web page its chat is embedded in, so the page can react to the conversation: open a product, fill in a form, go to checkout. Found in the agent sidebar under Tools → Page Events. Changes are kept on the page until you click Save all changes. For a walkthrough, see Make Your Page React to the Agent.
Page Events
| Only on a page that embeds the chat | A note that the agent is offered page events only while its chat runs inside the qlar widget on a web page, not on WhatsApp or the standalone chat. It links to Channels › Embed and opens the builder. |
| Add page event | Opens the New Page Event panel. |
| Page event row | Shows the action name, the event name and the description. Click it to open Edit Page Event. |
| Enabled switch | Turns the page event on or off without deleting it. While it is off, the row is dimmed with an Off chip, the agent is not offered it, and the embed builder does not list it. Takes effect when you save. |
| Delete button | Removes the page event from the list, after you confirm. |
| Empty state | "No page events yet" is shown when the agent has none. |
| Listen on your page | A code example that listens for qlarPageEvent on the widget element. |
| Save all changes | Saves every page event after you confirm. |
New Page Event / Edit Page Event
Basic Information
| Action Name | Required. The name the AI knows the action by, for example show_product. |
| Event Name | Required. What the page receives as event.detail.name, for example open_product. Starts with a letter and uses only letters, digits, _, -, . or :, up to 64 characters. Two page events cannot share an event name. |
| Description | What the event does on the page and when to send it. The AI decides from this text. |
| Rules | Optional. Extra conditions for sending the event. |
Parameters
The values the AI fills in from the conversation. The page receives them as event.detail.parameters. qlar refuses an event whose values do not match the definitions, and the AI tries again.
| Property Name | Required. The key in event.detail.parameters. Two properties cannot share a name. |
| Property Type | Required. String, Number or Boolean. |
| Required Parameter | On: the event is not sent without this value. |
| Property Enum | Optional. The only values allowed. Press Enter after each one. |
| Property Description | Tells the AI what to put in the property. |
| Add New Property | Adds a property. The trash icon removes one, after you confirm. |
A page event has no request, so unlike a Custom API there is no location, HTTP method, URL, authentication or loading text.
Metadata
Filled in by qlar, never by the AI, and sent as event.detail.metadata. Every script on the embedding page can read it, so only values that are safe there are offered.
Agent ID (agentId) | The agent's published ID. On by default. |
Conversation ID (threadId) | The conversation's ID. It cannot be used to read the conversation. On by default. |
Message ID (messageId) | The ID of the visitor's message the event answers. On by default. |
Channel (channel) | text or voice. On by default. |
Timestamp (timestamp) | When the event was sent, in ISO 8601 UTC. On by default. |
User ID (userId) | The signed-in visitor's qlar user ID; empty for an anonymous visitor. Off by default. |
User email (userEmail) | The signed-in visitor's email address; empty for an anonymous visitor. Off by default. |
| Personal data warning | Shown when User ID or User email is on: the values go to the embedding page and every script on it, are never sent in privacy mode, and are empty for anonymous visitors. |
Organization and owner IDs, permissions, file links and messenger accounts are never sent to a page.
Add Page Event / Update Page Event
Checks the form and puts the page event in the list. It is saved with Save all changes.
What the Page Receives
The widget element dispatches a qlarPageEvent that bubbles. Its detail:
name | The event name. |
parameters | The parameters with the AI's values. |
metadata | The metadata you chose, with qlar's values. |
id | Unique per event. |
agentId | The data-agent-id of the widget that sent it. |
Events are sent once, while the conversation happens. Reopening a conversation does not send them again.