> For the complete documentation index, see [llms.txt](https://docs.nestjstools.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nestjstools.com/components/message-handlers.md).

# Message Handlers

## 📦 Message Handlers

Message handlers define how your application reacts to specific messages dispatched on a bus. They encapsulate business logic triggered by inter-service or internal communication.

This page explains how to define, register, and work with message handlers using `@nestjstools/messaging`.

***

### 🛠️ Defining a Message Handler

A message handler is a class that implements the `IMessageHandler<T>` interface for a specific message type.

#### Example:

```ts
import { Injectable } from '@nestjs/common';
import { MessageHandler, IMessageHandler, MessageResponse } from '@nestjstools/messaging';
import { SendMessage } from './send-message';

@Injectable()
@MessageHandler('your.message')
export class SendMessageHandler implements IMessageHandler<SendMessage> {
  async handle(message: SendMessage): Promise<MessageResponse | void> {
    console.log(message.content);
    // Your business logic here
  }
}
```

***

### 🔁 Handling Multiple Routes

You can bind the same handler to **multiple routing keys**:

```ts
@MessageHandler('your.message', 'alternate.route')
```

This is useful if the same logic should run for different message sources.

***

### 🧠 Typed Message Input with `@DenormalizeMessage()`

By default, the handler receives the raw message data (usually as a plain JavaScript object). If you want to receive it as a properly instantiated class, use the `@DenormalizeMessage()` decorator:

```ts
async handle(@DenormalizeMessage() message: SendMessage): Promise<void> {
  // Now message is an instance of SendMessage with all class logic available
}
```

This is especially helpful when your message class contains methods, getters, or requires validation logic.

***

### 🧩 Registering Handlers

Handlers are automatically discovered by NestJS as long as they are included in the providers of a module:

```ts
@Module({
  providers: [SendMessageHandler],
})
export class MessagingFeatureModule {}
```

If you use a feature module, ensure that the module is imported by the root module and that `MessagingModule` is globally available or also imported.

***

### 📤 Triggering Handlers

Handlers respond to messages dispatched through a message bus with a matching route:

```ts
await messageBus.dispatch(
  new RoutingMessage(new SendMessage('Hello!'), 'your.message'),
);
```

If a handler is decorated with `@MessageHandler('your.message')`, it will receive this message.

***

### Returning a Response

Handlers can return a `MessageResponse` if needed:

```ts
import { MessageResponse } from '@nestjstools/messaging';

return new MessageResponse({ result: 'OK' });
```

You can optionally implement response-handling logic in the calling component.

***

### Summary

| Concept                 | Description                                                                         |
| ----------------------- | ----------------------------------------------------------------------------------- |
| `@MessageHandler()`     | Binds a handler to one or more routes                                               |
| `IMessageHandler<T>`    | Interface for handling a specific message type                                      |
| `@DenormalizeMessage()` | Automatically deserializes message into class instance                              |
| `MessageResponse`       | Optional way to return structured results from handlers, you can also return object |

***

{% hint style="info" %}
Note that handlers are visible across channels
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nestjstools.com/components/message-handlers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.