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 (single agent or multi agent) 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.
Four 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 user message | Every user message turn. | Cross-cutting logic that should run alongside every reply - logging, analytics, context refresh. |
| On session complete | Once, when the session ends. | Terminal, fire-and-forget actions - close-out logging, a wrap-up workflow, writing a final variable. No AI reply is generated. |
| 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 user message
The On user message hook fires on every user message turn - alongside (not instead of) whatever agent handles the reply. Use it for cross-cutting work that should happen every turn regardless of which agent is active:
- Logging or analytics that need a record of every turn.
- Refreshing a piece of context (re-checking an external flag, updating a "last seen" timestamp).
Like the other action-based hooks, it runs a workflow or a Set Variable action; the workflow's output is stored in a variable so later turns can read it.
Step 4: On session complete
The On session complete hook fires once, when the session ends. It's a terminal, fire-and-forget hook - by the time it runs there's no more conversation to reply into, so it only runs its configured action (workflow or Set Variable); it does not produce an AI reply. Use it for:
- Close-out logging (session duration, outcome, resolution status).
- A wrap-up workflow (send a summary, update a CRM record).
Because nothing downstream reads its output, storing the workflow's result in a variable is optional for this hook only - every other hook still requires it, since their output feeds the turn that follows.
Step 5: 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