Producers

A producer is any service that generates and publishes notifications to Notiway. It can be written in any language. All it needs to do is publish a JSON message in the standard notification format to the configured broker (SNS, Redis, RabbitMQ, etc.).

Notiway handles everything after that: routing, persistence, and delivery to connected clients.

Notification Structure

Every notification is a JSON object with five top-level fields. Here is the simplest possible example for broadcasting to all connected clients:

{
  "id": "order-service-order-placed-2025-01-01T10:00:00Z",
  "type": "order-placed",
  "body": {
    "orderId": "abc-123",
    "total": 59.99
  },
  "routing": {
    "audienceType": 1,
    "audienceValue": "global"
  },
  "metadata": {
    "producer": "order-service",
    "timeStamp": "2025-01-01T10:00:00Z",
    "isPersisted": false
  }
}

Fields

Field	Type	Required	Description
`id`	string	Yes	Unique identifier for the notification. Recommended format: `{producer}-{type}-{timestamp}`
`type`	string	Yes	Free-form event name (e.g. `order-placed`, `alert`). Clients receive a notification only when they have subscribed to this notification type.
`body`	object	No	Any JSON payload. The schema is defined entirely by you.
`routing`	object	Yes	Determines who receives the notification. See Routing below.
`metadata`	object	Yes	Contextual information about the notification origin and persistence. See Metadata below.

Routing

The routing object controls which connected clients receive the notification. audienceType is an integer enum — see the Audience Types table below for all possible values.

Field	Type	Required	Description
`audienceType`	number	Yes	Integer enum defining the target audience scope.
`audienceValue`	string	Yes*	The target identifier (user ID, tenant ID, group name, or connection ID). *Required for all audience types except Global.
`tenantId`	string	No	Required when targeting a tenant-scoped group. For Tenant audience, either `audienceValue` or `tenantId` must be populated with the tenant identifier.

Audience Types

Value	Name	Who receives the notification	`audienceValue`
`1`	Global	All connected clients	Set to `"global"`
`2`	Tenant	All clients in the specified tenant	The tenant ID
`3`	Group	All clients that are members of the named group	The group name
`4`	User	All clients connected as the specified user	The user ID
`5`	Connection	The single client with the specified connection ID	The connection ID

Group + Tenant scoping: When targeting a group within a specific tenant, set audienceValue to the group name and tenantId to the tenant. Without tenantId, the group is global across all tenants.

Metadata

Field	Type	Required	Description
`producer`	string	Yes	Name of the service sending the notification (e.g. `"order-service"`). Used for tracing and logging.
`timeStamp`	string (ISO 8601)	Yes	UTC timestamp of when the notification was created.
`isPersisted`	boolean	No	If `true`, Notiway stores the notification so offline users receive it on reconnect. Defaults to `false`.
`persistedTTL`	string (ISO 8601)	No	Expiry time for the persisted notification. Defaults to 30 minutes from creation if not set.

Routing Examples

The routing field shown in each example below can be dropped into a full notification alongside id, type, body, and metadata.

Broadcast to all connected clients.

{
  "routing": {
    "audienceType": 1,
    "audienceValue": "global"
  }
}

All clients in a specific tenant. Use either audienceValue or tenantId — both refer to the tenant identifier.

{
  "routing": {
    "audienceType": 2,
    "audienceValue": "acme-corp"
  }
}

All clients in a named group, across all tenants.

{
  "routing": {
    "audienceType": 3,
    "audienceValue": "admins"
  }
}

All clients in a named group, scoped to a specific tenant.

{
  "routing": {
    "audienceType": 3,
    "audienceValue": "admins",
    "tenantId": "acme-corp"
  }
}

All clients connected as a specific user. A single user may have multiple active connections (e.g. browser + mobile).

{
  "routing": {
    "audienceType": 4,
    "audienceValue": "user-42"
  }
}

A single specific client connection. Use when you need to target one exact device or tab.

{
  "routing": {
    "audienceType": 5,
    "audienceValue": "connectionId-789"
  }
}

Persistence

When isPersisted is true, Notiway stores the notification using the configured Storage plugin. If a user is offline when the notification is sent, they will receive it immediately upon reconnecting, as long as the TTL has not expired.

Default TTL is 30 minutes if persistedTTL is not provided
Once expired, the notification is no longer delivered on reconnect
Use persistence for important events where guaranteed delivery matters (alerts, account changes, etc.)
A client will only receive a persisted notification on reconnect if it is part of the correct audience (based on routing) and has subscribed to the matching notification type

Sending to Notiway

Producers never communicate directly with the Notiway gateway. Instead, the producer publishes to a broker (SNS, Redis, RabbitMQ, etc.) and Notiway’s Buffer plugin consumes from it. This decouples your services from the gateway. your service doesn’t need to know how many gateway instances are running or where they are.

See Sending Notifications for broker-specific examples (SNS, Redis, RabbitMQ, Azure Service Bus, and more).

Related Docs

Sending Notifications — broker-specific examples for publishing notifications
Broker Plugins — available broker plugins and their configuration
Routing — detailed routing and audience targeting
Storage Plugins — persistence and storage plugin options
Client Connection — how clients connect and subscribe to notification types

Connection Management