Scenes

A Scene is a complete conversation flow. It can combine multiple steps into a sequence and defines what happens when all the required data is collected.

You define a scene using createScene:

import { createScene, createStep } from "@waylis/core";

const nameStep = createStep({
    key: "name",
    prompt: { type: "text", content: "What is your name?" },
    reply: { bodyType: "text" },
});

const ageStep = createStep({
    key: "age",
    prompt: { type: "text", content: "How old are you?" },
    reply: { bodyType: "number" },
});

const scene = createScene({
    steps: [nameStep, ageStep],
    handler: async (answers) => {
        return {
            type: "text",
            content: `Hello ${answers.name}, your age is ${answers.age}`,
        };
    },
});

• steps (required) — An ordered list of steps. Each step runs sequentially. Collected answers are stored by their key.
• handler (required) — A function called after all steps are complete.

Handlers

The handlers always returns system responses, which are shown to the user.

handler: async (answers) => {
    await yourCustomLogic(answers);
    return { type: "text", content: "Registration complete!" };
},

It also support for multiple responses at once if you need to send a reply with a different types (e.g., text + file).

handler: async (answers) => {
    const pdfFile = await yourCustomLogic(answers);
    return [
        { type: "text", content: "Thanks for your answers!" },
        { type: "file", content: pdfFile },
    ];
},

System responses

Inside the scene handler, you must return a SystemMessageBody. Exactly the same system message must be returned inside the prompt and handler from steps.

Each response consists of a type field and a corresponding content field (all correspondences can be found here).

The type values available for system responses are shown below:

Type	Description
text	plain text
markdown	text formated as markdown
file	a single file
files	multiple files
table	simple talbe with columns and rows
linechart	configurable line chart

Text response example:

return {
    type: "text",
    content: "This is simple text response!",
};

Markdown response example:

return {
    type: "markdown",
    content: "This is **simple** markdown _response_!",
};

TIP

Under the hood, markdown rendered by react-markdown package and remark-gfm plugin on the frontend side.

Single file response example:

const data = Buffer.from("hello world");
const file = await fileManager.uploadFile(data, {
    name: "text.txt",
    size: data.length,
});

return { type: "file", content: file };

TIP

file and files types are described in detail here.

Table response example:

const head = ["Header 1", "Header 2"];
const body = [
    [1, "hello"],
    [2, "world"],
    [3, "again"],
];

return { type: "table", content: { head, body } };

Line chart response example:

const data = [
    { day: "Mar 22", price: 5 },
    { day: "Mar 23", price: 7 },
    { day: "Mar 24", price: 4 },
    { day: "Mar 25", price: 2 },
    { day: "Mar 26", price: 6 },
];

const series = [{ name: "price", color: "blue.6" }];

return {
    type: "linechart",
    content: { data, dataKey: "day", series, curveType: "linear" },
};

TIP

You can also find linechart and table types in the examples.