Manage conversation lifecycle

​

Basic setup

import { Conversation } from "@botpress/runtime"
import { z } from "@botpress/sdk"

export default new Conversation({
  channel: "webchat.channel",
  state: z.object({
    topic: z.string().optional(),
  }),

  lifecycle: {
    nudge: { after: "5m", interval: "10m", max: 3 },
    expire: { after: "30m" },
  },

  handler: async (props) => {
    if (props.type === "nudge") {
      await props.conversation.send({
        type: "text",
        payload: { text: "Still there? Let me know if you need anything." },
      })
      return
    }

    if (props.type === "expire") {
      await props.conversation.send({
        type: "text",
        payload: { text: "Closing this session due to inactivity. Come back anytime!" },
      })
      return
    }

    await props.execute({ instructions: "You are a helpful assistant." })
  },
})

​

Concepts

​

Nudge

• Configurable - you set when the first one fires (after), how often to repeat (interval, defaults to after if omitted), and when to stop (max, unlimited if omitted)
• Auto-resetting - any user message resets the nudge timer
• Handler-controlled - the framework decides when to nudge, you decide what to say
• Workflow-aware - nudges are automatically suppressed while a workflow is running

​

Expiration

1. Your handler runs first (type: "expire") so you can send a goodbye message or save a summary
2. Then the framework takes over: cancels workflows, tags the conversation, resets state, clears the transcript

​

Session

const session = props.conversation.session

if (session) {
  console.log(`Session #${session.number}, status: ${session.status}`)
}

​

What happens when a conversation expires

​

Duration strings

​

Common patterns

​

Escalating nudges

if (props.type === "nudge") {
  const session = props.conversation.session!
  const messages = [
    "Still there? Take your time.",
    "Just checking in. Do you need help with anything?",
    "I'll close this session soon if you don't need anything else.",
  ]
  const text = messages[session.nudgeCount - 1] ?? messages[messages.length - 1]
  await props.conversation.send({ type: "text", payload: { text } })
  return
}

​

Welcome back after expiration

if (props.type === "message" && props.conversation.session?.number! > 1) {
  await props.conversation.send({
    type: "text",
    payload: { text: `Welcome back! This is session #${props.conversation.session!.number}.` },
  })
}

​

Nudge-only (no expiration)

lifecycle: {
  nudge: { after: "10m", interval: "30m", max: 2 },
}

​

Expiration-only (no nudges)

lifecycle: {
  expire: { after: "1h" },
}

​

Different timeouts per channel

// conversations/support.ts - aggressive nudging, short timeout
lifecycle: {
  nudge: { after: "3m", interval: "5m", max: 3 },
  expire: { after: "15m" },
}

// conversations/sales.ts - patient, longer timeout
lifecycle: {
  nudge: { after: "30m", max: 1 },
  expire: { after: "24h" },
}

​

Things to know

• Timers are wall-clock based. after: "5m" means 5 minutes of real time since the last user message, not “bot idle time.”
• Only user messages reset timers. Bot messages, events, and workflow callbacks do not reset the nudge/expire timers.
• Expiration always wins. Even if nudges are suppressed during a workflow, the expire timer keeps ticking. Set expire.after longer than your longest expected workflow.
• Session data survives expiration. session.number persists. Only user state and transcript are cleared.
• No behavior change without opt-in. Conversations without lifecycle work exactly as before.
• Lifecycle events are invisible to the LLM. Nudge and expire events are not added to the transcript. Only your handler’s send() calls appear in the conversation history.