restapi
This package gives access to Push Protocol (Push Nodes) APIs. Visit Developer Docs or Push.org to learn more.
Index
How to use in your app?
Installation
yarn add @pushprotocol/restapi ethers
or
npm install @pushprotocol/restapi ethers
Import in your file
import * as PushAPI from "@pushprotocol/restapi";
About blockchain agnostic address format
In any of the below methods (unless explicitly stated otherwise) we accept either -
Note - For chat related restapis, the address is in the format: eip155:<address> instead of eip155:<chainId>:<address>
- ETH address format: only for backwards compatibility.
(Example:
0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb
)
About generating the "signer" object for different platforms
When using in SERVER-SIDE code:
const ethers = require('ethers');
const PK = 'your_channel_address_secret_key';
const Pkey = `0x${PK}`;
const signer = new ethers.Wallet(Pkey);
When using in FRONT-END code:
import { useWeb3React } from "@web3-react/core";
.
.
.
const { account, library, chainId } = useWeb3React();
const signer = library.getSigner(account);
SDK Features
For Notification
Fetching user notifications
const notifications = await PushAPI.user.getFeeds({
user: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
env: 'staging'
});
Fetching user spam notifications
const spams = await PushAPI.user.getFeeds({
user: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
spam: true,
env: 'staging'
});
Allowed Options (params with * are mandatory)
Param | Type | Default | Remarks |
---|
user* | string | - | user account address (CAIP) |
page | number | 1 | page index of the results |
limit | number | 10 | number of items in 1 page |
spam | boolean | false | if "true" it will fetch spam feeds |
env | string | 'prod' | API env - 'prod', 'staging', 'dev' |
raw | boolean | false | if "true" the method will return unformatted raw API response |
Fetching user subscriptions
const subscriptions = await PushAPI.user.getSubscriptions({
user: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
env: 'staging'
});
where subscriptions
is a list of channels [{ channel: '0xaddress', ... }]
subscribed by the user.
Note: We can find out if a user is subscribed to a channel by checking if the channel address is present in the subscriptions list
Allowed Options (params with * are mandatory)
Param | Type | Default | Remarks |
---|
user* | string | - | user address (CAIP) |
env | string | 'prod' | API env - 'prod', 'staging', 'dev' |
Fetching channel details
const channelData = await PushAPI.channels.getChannel({
channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
env: 'staging'
});
Allowed Options (params with * are mandatory)
Param | Type | Default | Remarks |
---|
channel* | string | - | channel address (CAIP) |
env | string | 'prod' | API env - 'prod', 'staging', 'dev' |
Searching for channel(s)
const channelsData = await PushAPI.channels.search({
query: 'push',
page: 1,
limit: 20,
env: 'staging'
});
Allowed Options (params with * are mandatory)
Param | Type | Default | Remarks |
---|
query* | string | - | search query |
page | number | 1 | page index of the results |
limit | number | 10 | number of items in 1 page |
env | string | 'prod' | API env - 'prod', 'staging', 'dev' |
Opt in to a channel
await PushAPI.channels.subscribe({
signer: _signer,
channelAddress: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
userAddress: 'eip155:5:0x52f856A160733A860ae7DC98DC71061bE33A28b3',
onSuccess: () => {
console.log('opt in success');
},
onError: () => {
console.error('opt in error');
},
env: 'staging'
})
Allowed Options (params with * are mandatory)
Param | Type | Default | Remarks |
---|
signer* | - | - | Signer object |
channelAddress* | string | - | channel address (CAIP) |
userAddress* | string | - | user address (CAIP) |
verifyingContractAddress | string | - | Push communicator contract address |
onSuccess | function | - | on success callback |
onError | function | - | on error callback |
env | string | 'prod' | API env - 'prod', 'staging', 'dev' |
Opt out to a channel
await PushAPI.channels.unsubscribe({
signer: _signer,
channelAddress: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
userAddress: 'eip155:5:0x52f856A160733A860ae7DC98DC71061bE33A28b3',
onSuccess: () => {
console.log('opt out success');
},
onError: () => {
console.error('opt out error');
},
env: 'staging'
})
Allowed Options (params with * are mandatory)
Param | Type | Default | Remarks |
---|
signer* | - | - | Signer object |
channelAddress* | string | - | channel address (CAIP) |
userAddress* | string | - | user address (CAIP) |
verifyingContractAddress | string | - | Push communicator contract address |
onSuccess | function | - | on success callback |
onError | function | - | on error callback |
env | string | 'prod' | API env - 'prod', 'staging', 'dev' |
*Push communicator contract address
ETH Mainnet - 0xb3971BCef2D791bc4027BbfedFb47319A4AAaaAa
ETH Goerli - 0xb3971BCef2D791bc4027BbfedFb47319A4AAaaAa
Sending notification
Direct payload for single recipient(target)
const apiResponse = await PushAPI.payloads.sendNotification({
signer,
type: 3,
identityType: 2,
notification: {
title: `[SDK-TEST] notification TITLE:`,
body: `[sdk-test] notification BODY`
},
payload: {
title: `[sdk-test] payload title`,
body: `sample msg body`,
cta: '',
img: ''
},
recipients: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
env: 'staging'
});
Direct payload for group of recipients(subset)
const apiResponse = await PushAPI.payloads.sendNotification({
signer,
type: 4,
identityType: 2,
notification: {
title: `[SDK-TEST] notification TITLE:`,
body: `[sdk-test] notification BODY`
},
payload: {
title: `[sdk-test] payload title`,
body: `sample msg body`,
cta: '',
img: ''
},
recipients: ['eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', 'eip155:5:0xCdBE6D076e05c5875D90fa35cc85694E1EAFBBd1'],
channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
env: 'staging'
});
Direct payload for all recipients(broadcast)
const apiResponse = await PushAPI.payloads.sendNotification({
signer,
type: 1,
identityType: 2,
notification: {
title: `[SDK-TEST] notification TITLE:`,
body: `[sdk-test] notification BODY`
},
payload: {
title: `[sdk-test] payload title`,
body: `sample msg body`,
cta: '',
img: ''
},
channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
env: 'staging'
});
IPFS payload for single recipient(target)
const apiResponse = await PushAPI.payloads.sendNotification({
signer,
type: 3,
identityType: 1,
ipfsHash: 'bafkreicuttr5gpbyzyn6cyapxctlr7dk2g6fnydqxy6lps424mcjcn73we',
recipients: 'eip155:5:0xCdBE6D076e05c5875D90fa35cc85694E1EAFBBd1',
channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
env: 'staging'
});
IPFS payload for group of recipients(subset)
const apiResponse = await PushAPI.payloads.sendNotification({
signer,
type: 4,
identityType: 1,
ipfsHash: 'bafkreicuttr5gpbyzyn6cyapxctlr7dk2g6fnydqxy6lps424mcjcn73we',
recipients: ['eip155:5:0xCdBE6D076e05c5875D90fa35cc85694E1EAFBBd1', 'eip155:5:0x52f856A160733A860ae7DC98DC71061bE33A28b3'],
channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
env: 'staging'
});
IPFS payload for all recipients(broadcast)
const apiResponse = await PushAPI.payloads.sendNotification({
signer,
type: 1,
identityType: 1,
ipfsHash: 'bafkreicuttr5gpbyzyn6cyapxctlr7dk2g6fnydqxy6lps424mcjcn73we',
channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
env: 'staging'
});
Minimal payload for single recipient(target)
const apiResponse = await PushAPI.payloads.sendNotification({
signer,
type: 3,
identityType: 0,
notification: {
title: `[SDK-TEST] notification TITLE:`,
body: `[sdk-test] notification BODY`
},
payload: {
title: `[sdk-test] payload title`,
body: `sample msg body`,
cta: '',
img: ''
},
recipients: 'eip155:5:0xCdBE6D076e05c5875D90fa35cc85694E1EAFBBd1',
channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
env: 'staging'
});
Minimal payload for a group of recipient(subset)
const apiResponse = await PushAPI.payloads.sendNotification({
signer,
type: 4,
identityType: 0,
notification: {
title: `[SDK-TEST] notification TITLE:`,
body: `[sdk-test] notification BODY`
},
payload: {
title: `[sdk-test] payload title`,
body: `sample msg body`,
cta: '',
img: ''
},
recipients: ['eip155:5:0xCdBE6D076e05c5875D90fa35cc85694E1EAFBBd1', 'eip155:5:0x52f856A160733A860ae7DC98DC71061bE33A28b3'],
channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
env: 'staging'
});
Minimal payload for all recipients(broadcast)
const apiResponse = await PushAPI.payloads.sendNotification({
signer,
type: 1,
identityType: 0,
notification: {
title: `[SDK-TEST] notification TITLE:`,
body: `[sdk-test] notification BODY`
},
payload: {
title: `[sdk-test] payload title`,
body: `sample msg body`,
cta: '',
img: ''
},
channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
env: 'staging'
});
Graph payload for single recipient(target)
Make sure the channel has the graph id you are providing!!
const apiResponse = await PushAPI.payloads.sendNotification({
signer,
type: 3,
identityType: 3,
graph: {
id: '_your_graph_id',
counter: 3
},
recipients: 'eip155:5:0xCdBE6D076e05c5875D90fa35cc85694E1EAFBBd1',
channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
env: 'staging'
});
Graph payload for group of recipients(subset)
Make sure the channel has the graph id you are providing!!
const apiResponse = await PushAPI.payloads.sendNotification({
signer,
type: 4,
identityType: 3,
graph: {
id: '_your_graph_id',
counter: 3
},
recipients: ['eip155:5:0xCdBE6D076e05c5875D90fa35cc85694E1EAFBBd1', 'eip155:5:0x52f856A160733A860ae7DC98DC71061bE33A28b3'],
channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
env: 'staging'
});
Graph payload for all recipients(broadcast)
Make sure the channel has the graph id you are providing!!
const apiResponse = await PushAPI.payloads.sendNotification({
signer,
type: 1,
identityType: 3,
graph: {
id: '_your_graph_id',
counter: 3
},
channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
env: 'staging'
});
Allowed Options (params with * are mandatory)
Param | Type | Default | Remarks |
---|
signer* | - | - | Signer object |
channel* | string | - | channel address (CAIP) |
type* | number | - | Notification Type Target = 3 (send to 1 address), Subset = 4 (send to 1 or more addresses), Broadcast = 1 (send to all addresses) |
identityType* | number | - | Identity Type Minimal = 0, IPFS = 1, Direct Payload = 2, Subgraph = 3 } |
recipients* | string or string[] | - | for Notification Type = Target it is 1 address, for Notification Type = Subset, Broadcast it is an array of addresses (CAIP) |
notification.title* | string | - | Push Notification Title (not required for identityType IPFS, Subgraph) |
notification.body* | string | - | Push Notification Body (not required for identityType IPFS, Subgraph) |
payload.title | string | - | Notification Title (not required for identityType IPFS, Subgraph) |
payload.body | string | - | Notification Body (not required for identityType IPFS, Subgraph) |
payload.cta | string | - | Notification Call To Action url (not required for identityType IPFS, Subgraph) |
payload.img | string | - | Notification Media url (not required for identityType IPFS, Subgraph) |
payload.sectype | string | - | If Secret Notification then pass (not required for identityType IPFS, Subgraph) |
graph.id | string | - | graph id, required only if the identityType is 3 |
graph.counter | string | - | graph counter, required only if the identityType is 3 |
ipfsHash | string | - | ipfsHash, required only if the identityType is 1 |
expiry | number | - | (optional) epoch value if the notification has an expiry |
hidden | boolean | false | (optional) true if we want to hide the notification |
env | string | 'prod' | API env - 'prod', 'staging', 'dev' |
Notification Helper Utils
Parsing notifications
Utils method to parse raw Push Feeds API response into a pre-defined shape as below.
const apiResponse = await PushAPI.user.getFeeds({
user: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
raw: true,
env: 'staging'
});
const parsedResults = PushAPI.utils.parseApiResponse(apiResponse);
const [oneNotification] = parsedResults;
const {
cta,
title,
message,
app,
icon,
image,
url,
blockchain,
secret,
notification
} = oneNotification;
We get the above keys
after the parsing of the API repsonse.
Advanced Notifications (WIP)
DEPRECATED
Get a channel's subscriber list of addresses
const subscribers = await PushAPI.channels._getSubscribers({
channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
env: 'staging'
});
Allowed Options (params with * are mandatory)
Param | Type | Default | Remarks |
---|
channel* | string | - | channel address (CAIP) |
env | string | 'prod' | API env - 'prod', 'staging', 'dev' |
For Chat
Create user for chat
const user = await PushAPI.user.create({
account: '0xFe6C8E9e25f7bcF374412c5C81B2578aC473C0F7',
env: 'staging',
});
Allowed Options (params with * are mandatory)
Param | Type | Default | Remarks |
---|
account* | string | - | user address |
env | string | 'prod' | API env - 'prod', 'staging', 'dev' |
Get user data for chat
const user = await PushAPI.user.get({
account: '0xFe6C8E9e25f7bcF374412c5C81B2578aC473C0F7',
env: 'staging',
});
Allowed Options (params with * are mandatory)
Param | Type | Default | Remarks |
---|
account* | string | - | user address |
env | string | 'prod' | API env - 'prod', 'staging', 'dev' |
Fetching list of user chats
const chats = await PushAPI.chat.chats({
account: 0xFe6C8E9e25f7bcF374412c5C81B2578aC473C0F7,
pgpPrivateKey: decryptedPvtKey,
toDecrypt: true,
env: 'staging',
});
Allowed Options (params with * are mandatory)
Param | Type | Default | Remarks |
---|
account* | string | - | user address |
env | string | 'prod' | API env - 'prod', 'staging', 'dev' |
toDecrypt | boolean | false | if "true" the method will return decrypted message content in response |
pgpPrivateKey | string | null | mandatory for users having pgp keys |
Fetching list of user chat requests
const chats = await PushAPI.chat.requests({
account: 0xFe6C8E9e25f7bcF374412c5C81B2578aC473C0F7,
pgpPrivateKey: decryptedPvtKey,
toDecrypt: true,
env: 'staging',
});
Allowed Options (params with * are mandatory)
Param | Type | Default | Remarks |
---|
account* | string | - | user address |
env | string | 'prod' | API env - 'prod', 'staging', 'dev' |
toDecrypt | boolean | false | if "true" the method will return decrypted message content in response |
pgpPrivateKey | string | null | mandatory for users having pgp keys |
Fetching conversation hash between two users
const threadhash = await PushAPI.chat.conversationHash({
account: '20x18C0Ab0809589c423Ac9eb42897258757b6b3d3d',
conversationId: '0xFA3F8E79fb9B03e7a04295594785b91588Aa4DC8',
env,
});
Allowed Options (params with * are mandatory)
Param | Type | Default | Remarks |
---|
account* | string | - | user address |
env | string | 'prod' | API env - 'prod', 'staging', 'dev' |
conversationId* | string | - | receiver's address or chatId of a group |
Fetching history between two users
const chatHistory = await PushAPI.chat.history({
threadhash:threadhash.threadHash,
account: '0xFe6C8E9e25f7bcF374412c5C81B2578aC473C0F7',
pgpPrivateKey: decryptedPvtKey,
limit:2,
toDecrypt:true,
env:'staging',
});
Allowed Options (params with * are mandatory)
Param | Type | Default | Remarks |
---|
account* | string | - | user address |
env | string | 'prod' | API env - 'prod', 'staging', 'dev' |
threadhash* | string | - | conversation hash between two users |
toDecrypt | boolean | false | if "true" the method will return decrypted message content in response |
pgpPrivateKey | string | null | mandatory for users having pgp keys |
limit | number | 10 | number of messages between two users |
Fetching latest chat between two users
const chatHistory = await PushAPI.chat.latest({
threadhash:threadhash.threadHash,
account: '0xFe6C8E9e25f7bcF374412c5C81B2578aC473C0F7',
pgpPrivateKey: decryptedPvtKey,
limit:2,
toDecrypt:true,
env:'staging',
});
Allowed Options (params with * are mandatory)
Param | Type | Default | Remarks |
---|
account* | string | - | user address |
env | string | 'prod' | API env - 'prod', 'staging', 'dev' |
threadhash* | string | - | conversation hash between two users |
toDecrypt | boolean | false | if "true" the method will return decrypted message content in response |
pgpPrivateKey | string | null | mandatory for users having pgp keys |
To approve a chat request
const response = await PushAPI.chat.approve({
status: 'Approved',
account: '0x18C0Ab0809589c423Ac9eb42897258757b6b3d3d',
senderAddress : '0x873a538254f8162377296326BB3eDDbA7d00F8E9',
env:'staging',
});
Allowed Options (params with * are mandatory)
Param | Type | Default | Remarks |
---|
account* | string | - | user address |
env | string | 'prod' | API env - 'prod', 'staging', 'dev' |
senderAddress* | string | - | receiver's address or chatId of a group |
status | 'Approved' | 'Approved' | flag for approving and rejecting chat request, supports only approving for now |
To send a message
const response = await PushAPI.chat.send({
messageContent: 'Hi',
messageType: 'Text',
receiverAddress: '0x08E834a388Cee21d4d7571075146841C8eE621a4',
account: '0x57eAd5826B1E0A7074E1aBf1A062714A2dE0f8B4',
pgpPrivateKey: decryptedPvtKey,
apiKey:"tAWEnggQ9Z.UaDBNjrvlJZx3giBTIQDcT8bKQo1O1518uF1Tea7rPwfzXv2ouV5rX9ViwgJUrXm"
env: 'staging',
});
Allowed Options (params with * are mandatory)
Param | Type | Default | Remarks |
---|
account* | string | - | user address |
env | string | 'prod' | API env - 'prod', 'staging', 'dev' |
senderAddress* | string | - | receiver's address or chatId of a group |
messageContent | string | '' | message to be sent |
messageType | 'Text' | 'Image' | 'File' | 'GIF' | 'Text' | type of messageContent |
pgpPrivateKey | string | null | mandatory for users having pgp keys |
apiKey | string | '' | apiKey for using chat |
To get group details by chatId
const response = await PushAPI.chat.getGroup({
chatId: '190591e84108cdf12e62eecabf02ddb123ea92f1c06fb98ee9b5cf3871f46fa9',
env: 'staging',
});
Allowed Options (params with * are mandatory)
Param | Type | Default | Remarks |
---|
chatId* | string | - | group chat id |
env | string | 'prod' | API env - 'prod', 'staging', 'dev' |
To create a group
const response = await PushAPI.chat.createGroup({
groupName:'Push Protocol group',
groupDescription:'This is the oficial group for Push Protocol,
members: ['0x9e60c47edF21fa5e5Af33347680B3971F2FfD464','0x3829E53A15856d1846e1b52d3Bdf5839705c29e5'],
groupImage: <group image link> ,
admins: ['0x3829E53A15856d1846e1b52d3Bdf5839705c29e5'],
isPublic: true,
account: '0xD993eb61B8843439A23741C0A3b5138763aE11a4',
env: 'staging',
pgpPrivateKey: decryptedPvtKey, //decrypted private key
});
Allowed Options (params with * are mandatory)
Param | Type | Default | Remarks |
---|
account* | string | - | user address |
env | string | 'prod' | API env - 'prod', 'staging', 'dev' |
groupName* | string | - | group name |
groupDescription* | string | - | group description |
groupImage* | string | - | group image link |
members* | Array | - | wallet addresses of all members except admins and groupCreator |
admins* | Array | - | wallet addresses of all admins except members and groupCreator |
isPublic* | boolean | - | true for public group, false for private group |
pgpPrivateKey | string | null | mandatory for users having pgp keys |
To update group details
Note - updateGroup is an idompotent call
const response = await PushAPI.chat.updateGroup({
groupName:'Push Chat group',
groupDescription:'This is the updated description for Push Chat,
members: ['0x2e60c47edF21fa5e5A333347680B3971F1FfD456','0x3829E53A15856d1846e1b52d3Bdf5839705c29e5'],
groupImage: <group image link> ,
admins: ['0x3829E53A15856d1846e1b52d3Bdf5839705c29e5'],
account: '0xD993eb61B8843439A23741C0A3b5138763aE11a4',
env: 'staging',
pgpPrivateKey: decryptedPvtKey, //decrypted private key
});
Allowed Options (params with * are mandatory)
Param | Type | Default | Remarks |
---|
account* | string | - | user address |
env | string | 'prod' | API env - 'prod', 'staging', 'dev' |
groupName* | string | - | group name |
groupDescription* | string | - | group description |
groupImage* | string | - | group image link |
members* | Array | - | wallet addresses of all members except admins and groupCreator |
admins* | Array | - | wallet addresses of all admins except members and groupCreator |
pgpPrivateKey | string | null | mandatory for users having pgp keys |
Chat Helper Utils
Decrypting encrypted pgp private key
import { IUser } from '@pushprotocol/restapi';
const decryptedPvtKey = await PushAPI.chat.decryptWithWalletRPCMethod(
(connectedUser as IUser).encryptedPrivateKey,
'0xFe6C8E9e25f7bcF374412c5C81B2578aC473C0F7'
);
Decrypting messages
import { IUser } from '@pushprotocol/restapi';
const decryptedChat = await PushAPI.chat.decryptConversation({
messages: chatHistory,
connectedUser,
pgpPrivateKey:decryptedPvtKey,
env:'staging',
});
Allowed Options (params with * are mandatory)
Param | Type | Default | Remarks |
---|
env | string | 'prod' | API env - 'prod', 'staging', 'dev' |
messages* | string | - | array of message object fetched from chat.history method |
connectedUser* | IUser | false | user meta data object |
pgpPrivateKey | string | null | mandatory for users having pgp keys |