# Messaging

The messaging service provides an internal communication channel between an app and its blocks. This allows for coordination and information sharing within an app installation, without the overhead or visibility of the [events system](./events).

## Overview
[Section titled “Overview”](#overview)
Internal messages are a lightweight mechanism for communication between components within the same app installation:

 - **App-to-block communication**: The app can send messages to specific blocks it manages
 - **Block-to-app communication**: Blocks can send messages to their parent app
 - **Block-to-block communication**: Blocks can send messages to other blocks within the same app
 - **Private communication**: Unlike events, messages are not visible in the UI and don’t establish connections
 - **Coordinated delivery**: Messages are collected during execution and delivered as a batch

This service is particularly useful for:

 - Routing incoming webhook payloads to interested blocks
 - Coordinating related blocks without visible event connections
 - Broadcasting information to multiple blocks
 - Implementing pub/sub patterns within an app

## Scope and boundaries
[Section titled “Scope and boundaries”](#scope-and-boundaries)
Internal messaging is strictly bounded by the app installation:

 - Messages can only flow between components within the same app installation
 - Blocks can message other blocks, but must know their block IDs
 - Messages cannot cross app installation boundaries under any circumstances
 - All messaging routes are defined in code by developers, not by user-configured connections

This boundary provides a clean separation of concerns and ensures that apps have complete control over their internal communication.


**

```
┌────────────────── App Installation ──────────────────┐│                                                      ││       ┌────────┐          ┌────────┐                 ││       │        │◄────────►│        │                 ││       │ Block  │          │  App   │                 ││       │   A    │◄────────►│        │                 ││       └────────┘          │        │                 ││            ▲              │        │                 ││            │              │        │                 ││            ▼              │        │                 ││       ┌────────┐          │        │                 ││       │        │◄────────►│        │                 ││       │ Block  │          │        │                 ││       │   B    │          │        │                 ││       └────────┘          └────────┘                 ││                                                      │└──────────────────────────────────────────────────────┘    │                                             │    ×             Cannot cross boundary           ×    │                                             │┌────────────────── Another App ─────────────────────┐│                                                    ││                                                    │└────────────────────────────────────────────────────┘
```

## Messaging vs. events
[Section titled “Messaging vs. events”](#messaging-vs-events)
For user-visible workflow orchestration, use the [events system](./events) instead. Messages are for internal app coordination only.

| Feature | Internal messages | Events |
| --- | --- | --- |
| **Visibility** | Private to the app | Visible in UI |
| **Connections** | Implicit | Explicit socket connections |
| **Routing** | Code-controlled | Connection-based |
| **Scope** | Within a single app installation only | Can span across different apps |
| **Configuration** | Defined by developers in code | Defined by users in the UI |
| **Use case** | Internal coordination | Workflow orchestration |
| **UI presence** | No UI representation | Visible in event history |
| **Recipient awareness** | Dynamic, determined at runtime | Static, based on connections |

## Communication patterns
[Section titled “Communication patterns”](#communication-patterns)
The internal messaging system supports these patterns:

| Pattern | Supported | Notes |
| --- | --- | --- |
| App → Specific block | ✓ Yes | Direct communication |
| App → Multiple blocks | ✓ Yes | Broadcast or targeted group |
| Block → Parent app | ✓ Yes | Direct communication |
| Block → Block (same app) | ✓ Yes | Must know the receiving block ID |
| Block → Block (different app) | ✗ No | Impossible with messaging (use events instead) |

## Sending messages
[Section titled “Sending messages”](#sending-messages)
### Sending to the app
[Section titled “Sending to the app”](#sending-to-the-app)
Any block can send messages to its parent app using:


**

```
import { messaging } from "@slflows/sdk/v1";
// Send a message to the parent appawait messaging.sendToApp({  body: {    type: "status_update",    blockId: input.block.id,    status: "ready",    timestamp: Date.now(),  },});
```

### Sending to blocks
[Section titled “Sending to blocks”](#sending-to-blocks)
Both apps and blocks can send messages to specific blocks using:


**

```
import { messaging } from "@slflows/sdk/v1";
// Send a message to specific blocksawait messaging.sendToBlocks({  blockIds: ["block-123", "block-456"],  body: {    type: "config_update",    newSettings: { timeout: 30 },  },});
```

### Discovering blocks
[Section titled “Discovering blocks”](#discovering-blocks)
Use the `blocks.list()` function to discover blocks within your app installation:


**

```
import { messaging, blocks } from "@slflows/sdk/v1";
// Discover blocks of a specific typeconst targetBlocks = await blocks.list({  typeIds: ["dataProcessor"],});
// Send message to discovered blocksawait messaging.sendToBlocks({  blockIds: targetBlocks.map(b => b.id),  body: {    type: "data_update",    payload: newData,  },});
```

Service discovery

Use `blocks.list()` to discover other blocks within your app installation. This is particularly useful when you need to coordinate with blocks of a specific type without hard-coding block IDs.

## Receiving messages
[Section titled “Receiving messages”](#receiving-messages)
To receive messages in an app or a block, implement the `onInternalMessage` handler:


**

```
{  onInternalMessage: async (input) => {    const { message } = input;    console.log(`Received message ${message.body}`);  },}
```

Message body

Flows does not enforce any specific structure on the message body. It can be any JSON-serializable object. It’s up to the sender and receiver to agree on the structure and content of the messages, but given that they’re internal to one app, this agreement is usually straightforward.

## Transaction model
[Section titled “Transaction model”](#transaction-model)
Internal messages are not sent immediately when the `sendToApp` or `sendToBlocks` functions are called. Instead:

 1. Messages are collected during the current execution
 1. When the execution completes, all messages are delivered in a batch
 1. This ensures that messaging operations are part of the overall transaction

This model has important implications:

 - Messages won’t be delivered if the execution fails
 - You won’t receive a response to your message in the same execution
 - Multiple messages can be sent in a single execution and will be delivered together