Heliont Messaging Hub — n8n Custom Nodes

A powerful messaging framework for n8n workflows, built for flexibility, interoperability, and flow-based contracts.

✨ Overview

The Heliont Messaging Hub is a modular and extensible node suite for n8n that provides:

• Contract-based data routing and transformation
• Seamless message handoff between workflows
• Multi-provider message normalization (Meta, Twilio, WhatsApp, etc.)
• Inbound and outbound messaging pipelines with queueing and database persistence

It is ideal for conversational platforms, chatbots, middleware, and data brokers that require structured message orchestration.

---

📦 Nodes Included

🧠 Contract Generator

Creates a global contract object that can be reused across the workflow or multiple workflows. Think of it as the shared schema / context for a conversation.

• Input: JSON contract definition
• Outputs:
  • Forwarded data (with contract key stripped)
  • Contract as a separate output
• Use at the start of a workflow

---

🛠️ Contract Recalibrator

Modifies the in-memory contract object.

• Add or update fields using dot notation (botUser.name)
• Remove fields from the contract dynamically
• Use case: enrich contract mid-flow (e.g., add resolved user ID)

---

📤 Contract Provider

Retrieves the current global contract.

• Forwards original data
• Outputs the current contract state
• Use case: inspect or fork contract logic elsewhere in the flow

---

🧬 Contract Teleporter

Teleports contract + input data to another workflow.

• Target workflow ID required
• Fire-and-forget or wait-for-completion modes
• Use case: modular microflows, decoupled worker logic

---

🧲 Contract Rematerializer

Restores contract + input data in a receiving workflow.

• Typically the first node in a target workflow receiving from Contract Teleporter
• Reinstates contract in memory
• Outputs:
  • Input items (cleaned)
  • Rehydrated contract

---

📥 Heliont Messaging Receiver

Receives and stores inbound messages.

• Parses raw messages using the contract's provider and version
• Stores normalized message into a database
• Outputs: bot_message_type, bot_message_content, and timestamp

---

📤 Heliont Messaging Sender

Creates, queues, and/or sends outbound messages.

• Uses contract data to build outbound messages
• Modes:
  • createMessage: Build but do not send
  • sendQueue: Send previously queued
  • createAndSendQueue: Build and send
  • sendInstant: Build and send immediately, no persistence
• Output: summary (createdCount, sentCount, etc.) + forwarded items

---

🧩 Contract Pattern

This package follows a flow contract pattern, where a JSON-based contract is initialized at the start and accessed across the workflow. This pattern:

• Decouples logic from implementation
• Enables cross-workflow context sharing
• Standardizes how messages are parsed, stored, and sent

Example contract keys:

{
  "botSystem": {
    "provider": "meta",
    "api-version": "v22.0",
    "botId": "123456"
  },
  "botMessage": {
    "rawMessage": "{...}"
  },
  "botUser": {
    "id": "user-uuid",
    "name": "John Doe"
  }
}

---

🔗 Installation

1. Add to your n8n environment:

npm install @heliont/n8n-nodes-messaging-hub

2. Ensure your custom nodes directory is configured in n8n.

N8N_CUSTOM_EXTENSIONS=/path/to/custom-nodes

3. Restart n8n:

n8n stop && n8n start

---

🛡️ Authentication

Some nodes require a Heliont Messaging Hub Credential, which typically includes database access information. Ensure this credential is created in the n8n UI under Credentials > Heliont Messaging Hub.

---

🛠️ Dependencies

• n8n >= 1.0.0
• Relies on global workflow memory (getWorkflowStaticData('global'))
• Compatible with structured messaging from platforms like Meta, Twilio, etc.

---

📚 Examples

• Contract-first flow: initialize → enrich → send
• Cross-workflow: contract + input → teleporter → rematerializer → receiver
• Bot platform integration: normalize inbound from Meta API → store → respond

---

🧠 Design Philosophy

This node suite is designed for enterprise-grade conversation flows, with:

• Modular, testable nodes
• Memory-safe contract operations
• Clean separation of routing vs business logic
• Support for both linear and branched flow architectures

---

📄 License

MIT License — see LICENSE

---

💡 Author

Made with 💚 by Heliont — powering secure identity, messaging, and automation infrastructure.