Steps

An action is built from steps, connected top to bottom. This page describes each one. Open an action in Dashboard → Actions and use Add step to place them.

Start

Every action has exactly one Start. It decides when the action runs (see When an action runs) and what the action receives.

Description for the AI. For an action the AI starts, this is what the assistant reads. The assistant sees the action as a tool named after it, so write when to use it: “Use when the visitor wants a callback from sales.”

Inputs. The values the action needs to begin. Each has a name, a type (text, number, true or false, list of text, list of numbers), and whether it is required. For an AI-started action, the AI fills them in from the conversation, so add a short description of what belongs in each. For actions that run when the chat starts or ends, inputs are filled by name from your External Variables.

Message

Says something to the visitor and, if you want, waits for a response. Choose how they respond:

• Message only shows the text for a few seconds (three by default), then moves on.
• Single select offers choices and follows the path of the one they pick.
• Multi-select lets them pick several.
• Form asks for one or more fields.

Form fields can be text, email, phone, number, date, URL, name, address, or yes/no. Mark a field required, add placeholder text, and set limits such as a pattern, minimum and maximum, or length.

In voice and avatar chats, a Message step can be said aloud as well as shown. A choice question can also let the visitor answer by voice (off by default). Ragtime matches what they say to one of your options, using the option’s own words first and a small AI check when that fails, and submits the match as if they had clicked it. Everywhere else a form holds the microphone, and the microphone is also off once Ragtime detects the end of the session.

Each choice can lead to a different next step, and separate branches can meet again on a later step.

Condition

Chooses a path from data the action already has. It can compare an answer, a Start input, or an HTTP response, and check it against a fixed value or against another answer.

Rules are grouped. Rules within a group are alternatives (any one is enough), and every group must pass. The operators are equals, not equals, contains, doesn’t contain, greater than, less than, is empty, is not empty, in list, not in list, and matches regex.

HTTP request

Calls another system.

• Method and URL. GET, POST, PUT, DELETE, or PATCH. The URL can contain {name} placeholders, filled from the values you send.
• Headers. For keys and other credentials.
• Values it sends. Each has a name, a type, and whether it is required, and each is linked to a source. See Start inputs and values.

Ragtime waits for the response before moving on, showing the chat’s thinking dots. Later steps can use the whole response or one value in it. The URL and headers stay on the server, so credentials never reach the visitor’s browser.

Note

If an action starts on the server and later reaches a step that asks the visitor, the responses fetched so far are not sent to the browser. Steps that ask the visitor cannot use them, and the editor only offers what a step can safely read.

Page event

Tells the web page around the assistant that something happened, so the page can react: open a panel, show a banner, select a product.

Give the event a name (for example lead_captured) and any values to send. The embedding page receives a ragtime-action message:

window.addEventListener('message', (event) => {
  if (event.data?.type === 'ragtime-action') {
    console.log(event.data.action, event.data.args);
  }
});

action is the event name and args holds the values. See Embedding for the rest of the message protocol.

This step sends a message from Ragtime to your page. For messages the other way, from your page to the conversation, see Page events.

Run another action

Runs a different action in place and continues when it ends. Fill in the other action’s Start inputs like any other values. Its steps run from its own graph, and an action cannot run itself, directly or through others. Use it to reuse a sequence, or to split a long action into parts.

End

Ends the action. Choose what happens next:

• Continue to open chat. The visitor carries on talking to the assistant.
• End session. Closes the conversation.

For an action the AI started that finishes without asking the visitor anything, you can also choose what goes back to the AI: nothing (the AI hears that it ran), an HTTP response (whole, or one value by path), or one of the Start inputs. Once the visitor has answered a question, their answers go back into the conversation instead.

In an LMS launch, an End step can also report completion, with an optional score, to the LMS. See LTI.

Limits

Ragtime caps how much an action can do at once: a server-run action stops after a fixed number of steps, and a single assistant reply can only start a limited number of server actions. Both exist to stop a loop from running away.