Lifecycle hooks
Lifecycle hooks let you run cross-cutting behaviour at key moments in a conversation - at the start of a session, or when a user goes quiet. Because Lifecycle hooks live in Configuration, they are project-level: they apply across the bot, regardless of which agent (conversational or guided) happens to be handling the turn.
Most bots don't need any hooks. Reach for them when you want behaviour that isn't tied to a single reply - analytics, custom logging, dynamic context injection, or proactive nudges when a user stalls.
Note: Hooks are optional. Leaving them all off is a perfectly valid configuration - skip this page until you have a concrete cross-cutting need.
Step 1: Open Lifecycle hooks
In your bot, open AI Agent → Configuration, then select Lifecycle hooks (under Agents in the left menu).
The sub-page lists the available hooks. Each hook has an active toggle and an expand arrow to configure its rules and actions. A hook does nothing until you toggle it on and configure it.
Two hook types are available today:
| Hook | Fires when | Typical use |
|---|---|---|
| On session start | The user sends the first message and a new session begins. | One-time setup at the start of a conversation. |
| On inactivity | The user has been idle for a configurable duration. | Proactive nudges to re-engage a stalled user. |
Step 2: On session start
The On session start hook fires once, when a user sends their first message and a new session begins. Use it for one-time setup at the start of a conversation:
- Pre-load context (look up the customer, set Memory variables).
- Log the session for analytics.
- Run an onboarding workflow before the first reply.
Toggle the hook on, expand it, and attach the workflow or action you want to run on session start.
Step 3: On inactivity
The On inactivity hook fires after the user has been idle for a configurable duration. It is rules-based: you add up to 5 rules per agent, each with:
- A threshold - the idle duration before the rule fires (up to 59 minutes).
- A single workflow action - the workflow that runs when the threshold trips.
The workflow runs without an LLM round-trip - it's a deterministic nudge, so it's fast and predictable.
How it works
- Each inbound user message resets the timers.
- When a threshold elapses without a new user message, the matching rule fires its workflow.
- If multiple rules elapse at once (caused by a backend lag, say), only the largest-eligible threshold fires - so customers don't get a stack of stale nudges all at once.
Customer Support preset
A Customer Support preset ships an out-of-the-box ladder you can drop in as a starting point:
| Threshold | Intent |
|---|---|
| 60 s | Gentle nudge - "Are you still there?" |
| 180 s | Stronger nudge |
| 300 s | Hand-off |
Note: The preset is visible only in the empty state, so you can't accidentally clobber rules you've already authored. Once you add your own rules, the preset is no longer offered.
When to reach for it
- Customer support: re-engage idle users with "Are you still there?", then offer human handoff.
- Sales / booking: send an abandoned-cart-style nudge when a user stalls mid-form.
- Long-running flows: capture lead data before the session times out.
Best practices
- Keep thresholds short → long (60 s → 5 min). Stacking three nudges in quick succession reads as harassment.
- Start from the CS preset and tune the workflow contents to your tone and channel.
- Handle the missing-context case in the inactivity workflow - by the time it runs, the user may have left, so don't assume earlier session state is still meaningful.
- Don't over-hook. If a behaviour belongs to one agent's flow, put it in a tool or the agent itself rather than a project-level hook.
Once you've configured (or skipped) your hooks, validate them by sending a first message and then letting a session sit idle in the Testing Lab.
Next: Fallback