Skip to main content

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

// 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

ParamTypeSub-TypeDefaultRemarks
listenconstant--can be CONSTANTS.STREAM.CHAT, CONSTANTS.STREAM.CHAT_OPS, CONSTANTS.STREAM.NOTIF, CONSTANTS.STREAM.CONNECT, CONSTANTS.STREAM.DISCONNECT
optionsPushStreamInitializeProps--Optional configuration properties for initializing the stream.
-options.filterobject-Option to configure to enable listening to only certain chats or notifications.
-options.filter.channelsarray of strings['*']pass list of channels over here to only listen to notifications coming from them.
-options.filter.chatsarray of strings['*']pass list of chatids over here to only listen to chats coming from them.
-options.connectionobject-Option to configure the connection settings of the stream
-options.connection.retriesnumber3Number of automatic retries incase of error
-options.rawbooleanfalseIf 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 eventsWhen is it triggered?
CONSTANTS.STREAM.NOTIFWhenever a new notification is emitted for the wallet.
CONSTANTS.STREAM.CONNECTWhenever the stream establishes connection.
CONSTANTS.STREAM.DISCONNECTWhenever 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.

// 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

ParamTypeSub-TypeDefaultRemarks
listenconstant--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
newOptionsPushStreamInitializeProps--Optional configuration properties for initializing the stream.
-newOptions.filterobject-Configure to listen to specific chats or notifications.
-newOptions.filter.channelsarray of strings['*']Pass list of channels over here to only listen to notifications coming from them.
-newOptions.filter.chatsarray of strings['*']Pass list of chatids over here to only listen to chats coming from them.
-newOptions.connectionobject-Option to configure the connection settings of the stream
-newOptions.connection.retriesnumber3Number of automatic retries incase of error
-newOptions.rawbooleanfalseIf 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.

// 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.

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

typescript true // if connected, else false