ErisPulse ErisPulse
Open in interactive docs →
On this page
Static mirror — the interactive version is canonical Open in interactive docs →

Conversation Multi-turn Dialogue

Tip

When to read this: When you need a multi-turn dialogue state machine and checkpoint recovery. If not needed, you can skip this section, which won't affect the use of other features.

When a command requires continuously asking the user multiple steps of information (such as registration, collecting data, questionnaires, or setup wizards), use Conversation to string together "ask → wait for reply → validate → next step" within the same session. The conversation can be resumed from a checkpoint after timeout or restart.

Creating a Conversation

Create a conversation using the conversation() method of the Event object:

from ErisPulse.Core.Event import command

@command("quiz")
async def quiz_handler(event):
    conv = event.conversation(timeout=30)

    await conv.say("🎮 Welcome to the quiz!")

    answer = await conv.choose("Question 1: Who is the creator of Python?", [
        "Guido van Rossum",
        "James Gosling",
        "Dennis Ritchie",
    ])

    if answer is None:
        await conv.say("Timeout, try again next time!")
        return

    if answer == 0:
        await conv.say("Correct!")
    else:
        await conv.say("Incorrect, the correct answer is Guido van Rossum")

    conv.stop()

Core API

say(content, **kwargs)

Send a message, returning self to support method chaining:

await conv.say("Line 1").say("Line 2").say("Line 3")

You can also specify the sending method:

await conv.say("https://example.com/image.jpg", method="Image")

wait(prompt=None, timeout=None)

Wait for a user reply, returning an Event object or None (if timeout):

# Simple wait
resp = await conv.wait()
if resp:
    text = resp.get_text()

# Wait after sending a prompt
resp = await conv.wait(prompt="Please enter your name:")

# Use custom timeout (overrides the conversation default timeout)
resp = await conv.wait(prompt="Please reply within 10 seconds:", timeout=10)

confirm(prompt=None, **kwargs)

Wait for the user to confirm (yes/no), returning True / False / None (if timeout):

result = await conv.confirm("Are you sure you want to delete all data?")
if result is True:
    await conv.say("Deleted")
elif result is False:
    await conv.say("Cancelled")
else:
    await conv.say("Timeout, no reply")

Built-in recognized confirmation words: yes/是/确认/确定/好/ok/true/对/嗯/行/同意/没问题/可以/当然...

Built-in recognized denial words: no/否/取消/不/不要/不行/cancel/false/错/不对/别/拒绝...

choose(prompt, options, **kwargs)

Wait for the user to select from options, returning the option index (0-based) or None:

choice = await conv.choose("Please select a color:", ["Red", "Green", "Blue"])
if choice is not None:
    colors = ["Red", "Green", "Blue"]
    await conv.say(f"You selected {colors[choice]}")

Users can select by entering a number (1/2/3) or the option text (Red).

options_format="auto" (default) automatically chooses the built-in style based on the method: Markdown → unordered list, Html → ordered list, others → plain text list. It also supports "list", "inline", "md", "html", or a custom function.

Supports merge_prompt=True to merge into a single message, and placeholder control for option insertion position (default {options}, customizable via placeholder):

choice = await conv.choose(
    "## Please select\n{options}",
    ["Option A", "Option B"],
    method="Markdown",
    merge_prompt=True,
)

# Custom placeholder
choice = await conv.choose(
    "Please select: [choices]",
    ["Option A", "Option B"],
    placeholder="[choices]",
)

collect(fields, **kwargs)

Collect information in multiple steps, returning a data dictionary or None:

data = await conv.collect([
    {"key": "name", "prompt": "Please enter your name"},
    {"key": "age", "prompt": "Please enter your age",
     "validator": lambda e: e.get("alt_message", "").strip().isdigit(),
     "retry_prompt": "Age must be a number, please re-enter"},
    {"key": "city", "prompt": "Please enter your city"},
])

if data:
    await conv.say(f"Registration successful!\nName: {data['name']}\nAge: {data['age']}\nCity: {data['city']}")
else:
    await conv.say("Registration interrupted")

Field configuration:

Parameter Description Default
key Field key name (required) -
prompt Prompt message "Please enter {key}"
validator Validation function, receives Event, returns bool None
retry_prompt Retry prompt on validation failure "Invalid input, please re-enter"
max_retries Maximum retry attempts 3
condition Condition function, receives collected data dict, returns bool None

Conditional fields: Use condition to implement dynamic forms, where the field is only collected if the condition is met:

data = await conv.collect([
    {"key": "has_car", "prompt": "Do you have a car? (Yes/No)"},
    {"key": "car_brand", "prompt": "Please enter the car model",
     "condition": lambda d: d.get("has_car", "").lower() in ("yes", "y")},
])

stop()

Manually end the conversation, setting is_active to False:

conv.stop()

is_active

Whether the conversation is active:

if conv.is_active:
    await conv.say("The conversation is still ongoing")

Active State Management

stateDiagram-v2
    state "Active" as active
    state "Inactive" as inactive
    [*] --> active: event.conversation()
    active --> active: say / wait / confirm / choose / collect
    active --> inactive: stop()
    active --> inactive: wait() timeout
    active --> inactive: collect() timeout or retries exhausted
    inactive --> [*]

The conversation automatically becomes inactive under the following conditions:

  1. The stop() method is called.
  2. wait() returns None due to timeout.
  3. collect() returns None due to timeout or exhausted retries.

After becoming inactive, all interactive methods (wait/confirm/choose/collect) immediately return None and do not continue to wait for user input.

Branching and Jumping

@conv.branch(name) Decorator

Use branch() to register conversation branches and goto() to jump between branches:

@command("menu")
async def menu_handler(event):
    conv = event.conversation(timeout=60)

    @conv.branch("main")
    async def main_menu():
        await conv.say("=== Main Menu ===\n1. Personal Info\n2. Settings\n3. Exit")
        resp = await conv.wait()
        if resp is None:
            return
        text = resp.get_text().strip()
        if text == "1":
            await conv.goto("profile")
        elif text == "2":
            await conv.goto("settings")
        elif text == "3":
            await conv.say("Goodbye!")
            conv.stop()

    @conv.branch("profile")
    async def profile():
        await conv.say("=== Personal Info ===\nName: Alice\n0. Back")
        resp = await conv.wait()
        if resp and resp.get_text().strip() == "0":
            await conv.goto("main")

    @conv.branch("settings")
    async def settings():
        await conv.say("=== Settings ===\n1. Notification Switch\n0. Back")
        resp = await conv.wait()
        if resp and resp.get_text().strip() == "0":
            await conv.goto("main")

    await conv.start()  # Start from the first registered branch

conv.start(name=None)

Start the conversation, defaulting to the first registered branch:

await conv.start()          # Start from the first branch
await conv.start("settings") # Start from a specified branch

Context and Persistence

conv.context

Each conversation instance has a built-in context dictionary for sharing state between branches:

@conv.branch("step1")
async def step1():
    conv.context["username"] = resp.get_text().strip()
    await conv.goto("step2")

@conv.branch("step2")
async def step2():
    name = conv.context.get("username", "Unknown")
    await conv.say(f"Hello, {name}!")

save() / resume() / clear_saved()

Conversations support persistence, allowing recovery after timeout or interruption:

# Save conversation state (usually not called manually, see "Automatic Checkpoint" below)
await conv.save()

# ... Later in the same session, resume ...
conv2 = event.conversation()
if await conv2.resume():
    await conv2.say("Welcome back! Continue the previous conversation")
else:
    await conv2.say("No previous conversation found")

# Clear saved conversation
await conv.clear_saved()

The storage key includes the target dimension (conversation:{platform}:{user_id}:{target_id}), ensuring conversations for the same user in different sessions do not overlap; old format (without target) archives are automatically migrated during resume().

Automatic Checkpoint and Restart Recovery

Automatic Archiving

The framework automatically maintains checkpoints at the following times, usually without manually calling save():

Timing Behavior
goto() / start() branch jump Automatically save (current branch + context)
stop() / wait() timeout / collect() failure Automatically clear (conversation final state)

Checkpoint TTL

Archives include timestamps, and those exceeding ErisPulse.interaction.checkpoint_ttl (default 24 hours) are cleaned up:

  • Lazy discard: If an archive is found expired during resume, it is automatically discarded.
  • Background proactive cleanup: The framework has a periodic GC task (lazy-started after first use of checkpoints) that actively enumerates and deletes expired archives, preventing indefinite accumulation of expired checkpoints in storage during long-running operations. Archives cleaned up by this process are treated as "no checkpoint" if a session message is received afterward.
[ErisPulse.interaction]
checkpoint_ttl = 86400  # seconds

Automatic Recovery on Restart

After a framework restart, in-progress conversations (waiting coroutines in memory) are lost, but checkpoints remain. Register a resume factory via register_resume_handler so the framework can automatically resume conversations when the first message of that session is received after restart:

from ErisPulse.Core.Event.wrapper import Conversation

@Conversation.register_resume_handler()  # Optional: platform="onebot11" to limit platform
def make_conversation(event) -> Conversation:
    # Factory responsibility: Rebuild conversation and re-register all branches
    conv = event.conversation(timeout=60)

    @conv.branch("menu")
    async def menu(conv, event):
        ...

    return conv

After registration, when a user in the menu branch sends their first message after a restart, the framework automatically: restores context → claims the message → continues the conversation from the archived branch. If no factory is registered, this mechanism incurs zero overhead.

Resume Equals Takeover

Upon successful resume(), the framework automatically completes two tasks:

  1. Session takeover: Automatically acquire the session's mutual exclusion lease — other modules can sense "this user is currently occupied by a conversation" via sdk.interaction.get_owner_of(event); if the session is already occupied by another module, the resume is abandoned (returns False), avoiding conflicts between two conversations.
  2. History retrieval: Retrieve the last 10 messages from the session inbox into conv.recent_history (so AI modules can maintain uninterrupted LLM context after recovery); resume(with_history=0) can disable this.
if await conv.resume(with_history=20):
    for m in conv.recent_history:
        print(m["role"], ":", m["text"])

Manual Resume (Without Automatic Mechanism)

@command("continue")
async def continue_handler(event):
    conv = event.conversation()
    # ... register branches ...
    if await conv.resume():
        conv.goto(conv.get_current_branch())

Typical Workflow Patterns

Guided Registration

@command("register")
async def register_handler(event):
    conv = event.conversation(timeout=60)

    await conv.say("Welcome to registration!")

    data = await conv.collect([
        {"key": "username", "prompt": "Please enter a username (3-20 characters)",
         "validator": lambda e: 3 <= len(e.get_text().strip()) <= 20},
        {"key": "email", "prompt": "Please enter an email address",
         "validator": lambda e: "@" in e.get_text() and "." in e.get_text(),
         "retry_prompt": "Invalid email format, please re-enter"},
    ])

    if not data:
        await event.reply("Registration cancelled")
        return

    confirmed = await conv.confirm(
        f"Confirm registration details?\nUsername: {data['username']}\nEmail: {data['email']}"
    )

    if confirmed:
        await conv.say("✅ Registration successful!")
    else:
        await conv.say("❌ Registration cancelled")

Looping Conversation

@command("chat")
async def chat_handler(event):
    conv = event.conversation(timeout=120)
    await conv.say("Entering conversation mode, type 'exit' to end")

    while conv.is_active:
        resp = await conv.wait()
        if resp is None:
            await conv.say("Timeout, conversation ended")
            break

        text = resp.get_text().strip()

        if text == "exit":
            await conv.say("Goodbye!")
            conv.stop()
        elif text == "help":
            await conv.say("Available commands: exit, help, status")
        elif text == "status":
            await conv.say("Conversation is active")
        else:
            await conv.say(f"You said: {text}")