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:
- The
stop()method is called. wait()returnsNonedue to timeout.collect()returnsNonedue 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:
- 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. - 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}")
Related Documentation
- Event Wrapper Class - All methods of the Event object
- Event Handling Introduction - Basics of event handling