Channels

A channel is a named message stream. You publish messages to a channel and create subscriptions to receive them. Channels are the fundamental organising unit in npayload.

Channel types

Standard channels

The default. Every message published is stored immutably and delivered to every active subscription.

const channel = await npayload.channels.create({
  name: 'orders',
  description: 'Order lifecycle events',
  privacy: 'standard',
});

Compacted channels

Compacted channels retain only the latest message per key. When a new message with the same key is published, the previous message is replaced. This is ideal for state that changes over time.

const channel = await npayload.channels.create({
  name: 'inventory',
  description: 'Current stock levels per SKU',
  type: 'compacted',
});

// Later messages with the same key overwrite earlier ones
await npayload.messages.publish({
  channel: 'inventory',
  key: 'SKU-001',
  payload: { quantity: 42 },
});

Priority channels

Messages in priority channels are delivered in priority order rather than publish order. Higher priority messages are delivered first.

await npayload.messages.publish({
  channel: 'alerts',
  payload: { severity: 'critical', message: 'Database unreachable' },
  priority: 10, // Higher = delivered first
});

Privacy modes

Every channel has a privacy mode that controls who can read the message payload.

Standard (default)

All features available. npayload can read payloads for routing, filtering, and schema validation.

{ privacy: 'standard' }

Hybrid

Metadata (routing keys, timestamps, trace IDs) remains visible for routing and debugging. The payload is encrypted with keys that npayload does not hold.

{ privacy: 'hybrid' }

E2E (end-to-end)

Zero-knowledge encryption. npayload cannot read the payload or metadata. Only the publisher and subscriber hold the decryption keys. Routing is limited to channel-level only.

{ privacy: 'e2e' }

Channel settings

const channel = await npayload.channels.create({
  name: 'events',
  settings: {
    retentionDays: 90,
    maxMessageSize: 524288, // 512 KB
    maxSubscriptions: 50,
  },
});

Channel lifecycle

Channels have three states:

// Pause
await npayload.channels.pause('orders');

// Resume
await npayload.channels.resume('orders');

// Archive (soft delete)
await npayload.channels.archive('orders');

Cross-instance channels

When a channel spans multiple instances, npayload automatically replicates messages between them with exactly-once delivery guarantees.

Cross-instance channels enable:

• Multi-region messaging for data residency compliance
• Cross-organisation communication for B2B integrations
• Instance-to-instance routing with automatic discovery

Next steps

• Messages to understand what flows through channels
• Subscriptions to learn how messages are delivered
• API reference for the full channels API