Stream notifications overview

These APIs enable you to receive notifications ( inbox or spam ) in real time without polling the API. Push notification achieves this by the use of sockets.

Stream Notification API

js

// userAlice.stream(listen, {options?})
// Initial setup
const stream = await userAlice.initStream([CONSTANTS.STREAM.NOTIF], {
  filter?: {
    channels?: ['*'], // pass in specific channels to only listen to those
    chats?: ['*'], // pass in specific chat ids to only listen to those
  },
  connection?: {
    retries?: 3, // number of retries in case of error
  },
  raw?: false // enable true to show all data
})

// Listen for notifications events
stream.on(CONSTANTS.STREAM.NOTIF, (data: any) => {
  console.log(data)
})

// Connect stream, Important to setup up listen events first
stream.connect()

// stream supports other products as well, such as STREAM.CHAT, STREAM.CHAT_OPS
// more info can be found at push.org/docs/chat

---

Stream notification parameters

Param	Type	Sub-Type	Default	Remarks
listen	constant	-	-	can be CONSTANTS.STREAM.CHAT, CONSTANTS.STREAM.CHAT_OPS, CONSTANTS.STREAM.NOTIF, CONSTANTS.STREAM.CONNECT, CONSTANTS.STREAM.DISCONNECT
options	PushStreamInitializeProps	-	-	Optional configuration properties for initializing the stream.
-	options.filter	object	-	Option to configure to enable listening to only certain chats or notifications.
-	options.filter.channels	array of strings	['*']	pass list of channels over here to only listen to notifications coming from them.
-	options.filter.chats	array of strings	['*']	pass list of chatids over here to only listen to chats coming from them.
-	options.connection	object	-	Option to configure the connection settings of the stream
-	options.connection.retries	number	3	Number of automatic retries incase of error
-	options.raw	boolean	false	If enabled, will also respond with meta data useful in verifying the integrity of incoming chats or notifications among other things.

Note: Parameters in this style are mandatory.

Stream notifications listen events

Listen events	When is it triggered?
CONSTANTS.STREAM.NOTIF	Whenever a new notification is emitted for the wallet.
CONSTANTS.STREAM.CONNECT	Whenever the stream establishes connection.
CONSTANTS.STREAM.DISCONNECT	Whenever the stream gets disconnected.

Expected response (CONSTANTS.STREAM.NOTIF - Notification inbox stream)

{
  "event": "notification.inbox",
  "origin": "other",
  "timestamp": "2023-10-06T01:55:51.000Z",
  "from": "0xfFA1aF9E558B68bBC09ad74058331c100C135280",
  "to": [
    "eip155:0xffa1af9e558b68bbc09ad74058331c100c135280"
  ],
  "notifID": "1676",
  "channel": {
    "name": "Testing Sepolia",
    "icon": "https://gateway.ipfs.io/ipfs/bafybeifu3tisz7cntfnoolwe6tthi554b2cdl46jzcr5amo6swucyautzq/QmYZZnnEuTnzjkhhnRZWaHgYTeHsohLZEme9LomWRYQAZ5",
    "url": "https://dev.push.org/"
  },
  "meta": {
    "type": "NOTIFICATION.BROADCAST"
  },
  "message": {
    "notification": {
      "title": "Testing Sepolia - notification TITLE:",
      "body": "notification BODY"
    },
    "payload": {
      "title": "payload title",
      "body": "sample msg body",
      "cta": "",
      "embed": "",
      "meta": {
          "domain": "push.org"
      }
    }
  },
  "config": {
    "expiry": null,
    "silent": false,
    "hidden": false
  },
  "source": "ETH_TEST_SEPOLIA",
  "raw": {
    "verificationProof": "eip712v2:0xf2b50f07c7cdae4a493860554301dc017dd6f819f92db3aba534dffde210bfaa0f545818e919c42c3bb51181339af33ad83e3bc691ada7fcccdcbc7fb3b3abd91b::uid::feaa2d31-85ec-47d2-b38c-6f797f637de7"
  }
}

Expected response (CONSTANTS.STREAM.NOTIF - Notification spam stream)

{
  "event": "notification.spam",
  "origin": "other",
  "timestamp": "2023-10-06T01:55:51.000Z",
  "from": "0xfFA1aF9E558B68bBC09ad74058331c100C135280",
  "to": [
    "eip155:0x1f1a304af17f22cac91eeca5f31a0f814d752377"
  ],
  "notifID": "1677",
  "channel": {
    "name": "Testing Sepolia",
    "icon": "https://gateway.ipfs.io/ipfs/bafybeifu3tisz7cntfnoolwe6tthi554b2cdl46jzcr5amo6swucyautzq/QmYZZnnEuTnzjkhhnRZWaHgYTeHsohLZEme9LomWRYQAZ5",
    "url": "https://dev.push.org/"
  },
  "meta": {
    "type": "NOTIFICATION.TARGETED"
  },
  "message": {
    "notification": {
      "title": "Testing Sepolia - notification TITLE:",
      "body": "notification BODY"
    },
    "payload": {
      "title": "payload title",
      "body": "sample msg body",
      "cta": "",
      "embed": "",
      "meta": {
          "domain": "push.org"
      }
    }
  },
  "config": {
    "expiry": null,
    "silent": false,
    "hidden": false
  },
  "source": "ETH_TEST_SEPOLIA",
  "raw": {
    "verificationProof": "eip712v2:0x6b903f16d0ce87483643e1502e7416203cb7ecef0e947a497f0fb6fbe1c43c3511f2f602b757ab02c1be7daa07f3872ee14e4d05134f1ecb3d11fe58324422c01c::uid::6c0fad10-d1eb-4779-84d3-3a96bd96263f"
  }
}

Re-initialize notification stream

To reinstate a notification stream. Useful for updating an already initialized stream objects to add / remove listen events or filter options.

js

// await stream.reinit(listen, {newOptions?})
const newStream = await stream.reinit([
  CONSTANTS.STREAM.NOTIF, // Listen for notification events
  CONSTANTS.STREAM.CONNECT, // Listen for connection events
  CONSTANTS.STREAM.DISCONNECT, // Listen for disconnection events
]);

Reinstate Notification stream parameters

Param	Type	Sub-Type	Default	Remarks
listen	constant	-	-	Choose from various streams:CONSTANTS.STREAM.NOTIF, CONSTANTS.STREAM.SPACE, CONSTANTS.STREAM.SPACE_OPS, CONSTANTS.STREAM.CHAT, CONSTANTS.STREAM.CHAT_OPS, CONSTANTS.STREAM.VIDEO, CONSTANTS.STREAM.CONNECT, CONSTANTS.STREAM.DISCONNECT
newOptions	PushStreamInitializeProps	-	-	Optional configuration properties for initializing the stream.
-	newOptions.filter	object	-	Configure to listen to specific chats or notifications.
-	newOptions.filter.channels	array of strings	['*']	Pass list of channels over here to only listen to notifications coming from them.
-	newOptions.filter.chats	array of strings	['*']	Pass list of chatids over here to only listen to chats coming from them.
-	newOptions.connection	object	-	Option to configure the connection settings of the stream
-	newOptions.connection.retries	number	3	Number of automatic retries incase of error
-	newOptions.raw	boolean	false	If enabled, respond with metadata useful in verifying the integrity of incoming chats or notifications among other things.

Note: Parameters in this style are mandatory.

Stream info API

To get the info of the current stream.

js

// stream.info()
const streamInfo = await stream.info();

Expected response

{
  options: { raw: false, connection: { auto: true, retries: 3 }, env: 'prod' },
  listen: [ 'STREAM.NOTIF', 'STREAM.CONNECT', 'STREAM.DISCONNECT' ]
}

Stream status API

To get the connection status of the current stream.

js

// stream.connected()
const streamStatus = await stream.connected();

Expected response

true // if connected, else false