Page Events

An assistant cannot see the page it sits on. A visitor taps a room on a map and asks “how do I get there?”, and the assistant has no idea what “there” is. Page events close that gap. Your page sends a small, typed message when something happens, and the conversation reads it.

Page events are managed in Dashboard → Actions → Page events.

Note

Two features share a name and run in opposite directions. The Page event step in an action sends a message from Ragtime to your page. The Page events tab on this page declares messages your page sends to Ragtime.

How it works

1. You declare each event the page may send: its name, the values it carries, and one sentence describing it.
2. You turn on Accept page events for the channel that will receive them.
3. Your page sends the event with postMessage.
4. Ragtime checks the event against your declaration. If it fits, the assistant reads your sentence with the values filled in.

The assistant never reads what the page sent. It reads the sentence you wrote, with each value checked against its declared type first. A page can only send events you declared, and only values of the type you allowed.

Declare an event

Open Dashboard → Actions → Page events and add an event. Each event has:

• Name: what the page sends, for example place_selected. Lowercase letters, digits and underscores, starting with a letter, up to 40 characters.
• Effect: what happens when it arrives. See Effects.
• Parameters: the values the event carries, up to five. Each has a name (same rules as the event name), a type, and a switch for required.
• Sentence: what the assistant reads, up to 300 characters. Put each parameter in braces, as in The visitor has selected {place} on the map.
• Forget after: for events that keep state only: a number of seconds after which the value is dropped. Leave it at 0 to keep it for the session.

While you edit, the dialog shows an example sentence built from your first values, so you can read what the assistant will read. You can declare up to 20 events, and at most 10 of them can keep state.

Adding an event stores it right away, switched off. An event with problems, such as a placeholder that matches no parameter, is stored but ignored, and cannot be switched on until you fix it. Use the toggle in the list to park an event without deleting it.

Parameter types

Type	What it accepts
Text	Up to 200 characters, with whitespace collapsed.
Number	A number, with an optional minimum and maximum.
Yes/no	true or false.
Choice	One of up to 50 values you list. Each has a label, and the assistant reads the label, never the value the page sent.
ID	Letters, digits, _ and -, up to 64 characters.

A value that does not fit is refused. Ragtime never shortens or repairs it. The same types are used for External Variables, with the same limits.

Effects

Effect	What it does	Limits
Keep as state	Ragtime keeps the latest value of the event and the assistant reads it silently on every turn. Use it for what is on screen right now. Send args: null to clear it.
Shape the next reply	The next reply reads the event once, then forgets it. It is not announced.	Up to 5 events wait for the next reply. When a sixth arrives, the oldest is dropped.
Speak now	The assistant responds straight away.	At most 6 per session, at least 20 seconds apart, and one waiting at a time (a newer one replaces it). Needs a started conversation, a known page origin, and no open form.

Speak now costs a model turn, like any other request, and draws credits the same way. It does not count as a visitor turn or toward engagement numbers.

State is accepted before the conversation starts, which is the useful case when a visitor selects something before they say anything. It also survives a restart. It is not restored when a saved session resumes on a new page load, so the page should send its current state again.

Write the sentence

The sentence is the only text the assistant reads, so write it as a plain fact about the screen, in the present tense:

• The visitor has selected {place} on the map.
• The visitor failed the quiz on {topic}.
• The visitor is looking at the product {product}.

Choice parameters are filled with the label you wrote. Text parameters are placed on one line and handed to the assistant as untrusted data, because a page could put anything in them. Prefer a choice or an ID where you can.

Your sentences are screened for attempts to subvert the assistant’s rules when you publish, together with its instructions. Editing a sentence screens it again.

Turn on the channel

Page events are off by default on every channel. Turn them on under Deployment → Channels, in the channel’s settings, with Accept page events. Do it for the channel whose page will send the events.

• The members-only preview always accepts page events.
• If no channel accepts them when you add an event, the dashboard says so and links to Deployment. You can still choose Add it anyway to declare first.
• Switching off the last channel that accepts page events switches the events off too, after a warning in the channel form.

Send an event from the page

const frame = document.querySelector('iframe');
frame.contentWindow.postMessage(
  { type: 'ragtime-host', action: 'event', name: 'place_selected', args: { place: 'spa' } },
  'https://your-ragtime-instance.com'
);

If your channel uses a custom template, the starter HTML on Dashboard → Deployment → Custom template includes ready-made code for the events you declared, with a comment on each one’s effect. The names and values in it are ones Ragtime will accept.

Page events work in text, voice and avatar chats. The message format and the listener for replies are described in Embedding.

What the page hears back

Ragtime answers every event. host_event_accepted carries the event name and its effect. host_event_dropped carries the name, a reason and a message in plain words, so a silent drop never looks like an event you forgot to send.

Reason	Meaning
not_enabled	The channel does not accept page events.
not_declared	No event with this name is declared, or it is not published yet.
disabled	The event is switched off in the dashboard.
invalid_args	A value is undeclared, missing, or of the wrong type.
rate_limited	A limit from the effects table was hit. The message says which.
session_not_started	A speak now event arrived before the conversation started.
session_ended	The conversation has ended.
flow_active	A speak now event arrived while a form was open.
origin	A speak now event arrived from a page that sent no referrer.

Try them without a page

The assistant preview has a Page events button. It lists your enabled events, lets you fill in their values, and sends the same message a real page would through the same checks. It shows the accepted or dropped reply, so you can build the declarations before the page exists.

Declarations go live when you publish the assistant, like the rest of its configuration. See Preview & Publishing.

In transcripts

Accepted events appear in the transcript viewer between the turns they happened between. Ragtime rebuilds each sentence from your published declarations and shows text values as [text], so what a page typed never lands in the transcript. Events are stored beside the turns, so analysis and exports see the same turns as before. A transcript keeps up to 50 events.

Manage them through the API

GET /api/v1/projects/{projectId}/assistant/page-events (assistant:read) returns the events, what keeps any of them from being used, and the channels that accept them. PUT (assistant:write) replaces the whole list with { "pageEvents": [...] }, each event in the shape above, keeping the id of each event you keep. The MCP server offers both as get_page_events and save_page_events.

• Draft only. Changes go to the draft. Visitors get them, after their sentences are screened, at the next publish in the dashboard.
• Complete or nothing. The dashboard keeps an event you are still writing; the API saves only a list in which every event is complete. Every problem is reported at once, in details.problems (422).
• Strict fields. A misspelt field is refused rather than ignored.

Permissions

Anyone who can open the Actions page can look at the page events. Changing them also takes the Configure Assistant permission, because the assistant reads their sentences.

Example: a wayfinding kiosk

A kiosk shows a map. When the visitor taps a room, the page sends place_selected with the room, and the assistant can answer “how do I get there?” without asking which room.

Field	Value
Name	place_selected
Effect	Keep as state
Parameter	place, a choice with labels such as “the spa” and “the pool”
Sentence	The visitor has selected {place} on the map.

A second event, route_shown with a minutes number and the effect Shape the next reply, lets the page tell the assistant how long the route it just drew takes, so the reply after it can say “about three minutes”.