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.

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

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

For user-visible workflow orchestration, use the events system 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

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

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 app
await messaging.sendToApp({
  body: {
    type: "status_update",
    blockId: input.block.id,
    status: "ready",
    timestamp: Date.now(),
  },
});

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 blocks
await messaging.sendToBlocks({
  blockIds: ["block-123", "block-456"],
  body: {
    type: "config_update",
    newSettings: { timeout: 30 },
  },
});

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 type
const targetBlocks = await blocks.list({
  typeIds: ["dataProcessor"],
});

// Send message to discovered blocks
await messaging.sendToBlocks({
  blockIds: targetBlocks.map(b => b.id),
  body: {
    type: "data_update",
    payload: newData,
  },
});

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}`);
  },
});

Transaction model

Internal messages are not sent immediately when the sendToApp or sendToBlocks functions are called. Instead:

Messages are collected during the current execution
When the execution completes, all messages are delivered in a batch
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