Build Custom Automations with OpenClaw's New Message Lifecycle Hooks

OpenClaw 2026.2.17 introduces a powerful new feature for developers building custom integrations: message lifecycle hooks. These hooks let you tap into the messaging pipeline and react to messages as they flow in and out of your agent.

What Are Message Lifecycle Hooks?

Message lifecycle hooks are internal events that fire when messages are received or sent through your OpenClaw gateway. The two new events are:

• message:received — Fires when an inbound message arrives from any channel (Telegram, Discord, WhatsApp, etc.)
• message:sent — Fires when your agent sends a message out

These hooks include session-key correlation so you can track which conversation each message belongs to, and they maintain accurate success/error reporting even for chunked or best-effort deliveries.

Why This Matters

Before this update, building automations around message flow required custom channel middleware or external webhook integrations. Now you can hook directly into the message pipeline using OpenClaw's plugin system.

Use Cases

Here are some practical applications:

📊 Analytics and Logging Track message volume, response times, and channel activity. Log all conversations to an external system like Elasticsearch or your own database.

🔔 Custom Notifications Trigger alerts when specific keywords appear in messages, or notify a Slack channel when your agent receives messages from VIP users.

🔄 External Integrations Sync conversations with your CRM, create tickets in your support system, or forward messages to external services for processing.

🛡️ Moderation Pipelines Inspect outbound messages before they're sent, or log inbound messages for compliance and audit trails.

How to Use Them

Message lifecycle hooks are accessed through the OpenClaw plugin/extension system. You can create a plugin that listens for these events:

// Example plugin structure
module.exports = {
  name: 'message-logger',
  hooks: {
    'message:received': async (payload) => {
      // payload includes message content, channel, session key, etc.
      console.log('Received:', payload.message);
      // Send to your logging service
    },
    'message:sent': async (payload) => {
      // Track outbound messages
      console.log('Sent:', payload.message);
    }
  }
};

The hooks provide full context including the channel, session key, sender information, and message content—everything you need to build sophisticated automations.

Technical Details

From the release notes:

Hooks/Automation: bridge outbound/inbound message lifecycle into internal hook events (message:received, message:sent) with session-key correlation guards, while keeping per-payload success/error reporting accurate for chunked and best-effort deliveries.

This means the hooks are production-ready with proper error handling and correlation tracking built in. Chunked messages (like long responses split across multiple sends) are handled correctly, and best-effort deliveries report their actual status.

Getting Started

To start using message lifecycle hooks:

1. Update to OpenClaw 2026.2.17 or later
2. Create a plugin in your workspace's extensions/ directory
3. Export the hook handlers you need
4. Configure your gateway to load the extension

For more details on the plugin system, check the OpenClaw documentation.

Related

This feature was introduced in PR #9387. If you're building interesting automations with message hooks, share them with the community!