Initialize user overview
Before you can start sending messages, or create conditional access group for your community, or send those chat requests to Vitalik.eth. you will need to initialize a user or re-authenticate the user. To do so you will use PushAPI.initialize call from @pushprotocol/restapi package.
Initialize user API
- js
import { PushAPI, CONSTANTS } from '@pushprotocol/restapi';
// Initialize wallet user
// PushAPI.initialize(signer, {options?});
// 'CONSTANTS.ENV.PROD' -> mainnet apps | 'CONSTANTS.ENV.STAGING' -> testnet apps
const userAlice = await PushAPI.initialize(signer, {
env: CONSTANTS.ENV.STAGING,
});
// Check for errors in userAlice's initialization and handle them if any
if (userAlice.errors.length > 0) {
// Handle Errors Here
}
Note: If a signer is not provided, or if an invalid signer is passed, or the SDK fails to generate or decrypt keys for the signer, the PushAPI will switch to Read mode.
The function automatically initializes and returns the Push user profile object if one doesn't exist for the user or alternatively creates a new profile if the user has not been onboarded to Push network. This profile is used to interact with all function calls moving forward.
Using for Wallet Addresses
Push supports wallet addresses (EVM, with non-EVM coming soon). Simply passing the signer will ensure that the PushAPI is initialized with address of the wallet (derived by the signer).
tip
Passing null in the signer enables Read Only Mode. Read only mode allows you to use certain APIs that are not sensitive in nature like reading user profile, listing notifications that are not encrypted by the sender, listing chats, etc.
Using for Lens / Cyberconnect / Any NFTs
Push also supports Lens, Cyberconnect, NFT wallets and any EVM or non-EVM wallets ensuring cross-chain messaging or cross-nft messaging can become a reality.
You will need to pass the account parameter in options object while initializing to target them. This will ensure that the PushAPI is initialized for the right account.
Example
- NFT profile - Pass
nft:{chain_standard}:{nftChainId}:{nftContractAddress}:{nftTokenId} account-nft:eip155:11155111:0x42af3147f17239341477113484752D5D3dda997B:2:1683058528
Read about supported wallet standards to understand all supported formats for account parameter.
Initialize user parameters
When initializing your user, you can customize the process using several parameters. Here's a breakdown:
| Param | Type | Sub-Type | Default | Remarks |
|---|---|---|---|---|
signer | SignerType | - | - | Ethers or Viem Signer. Pass null and provide account to enable read only mode |
options | PushAPIInitializeProps | - | - | Optional configuration properties for initializing the PushAPI. |
| - | options.env | ENV | staging | API env - 'prod' or 'staging'. |
| - | options.progressHook | (progress: ProgressHookType) => void | - | A callback function to receive progress updates during initialization. Expand Progress Hook Type and Response dropdown below to learn more |
| - | options.account | string | - | The account to associate user with. If not provided, it is derived from signer. |
| - | options.version | string | ENC_TYPE_V3 | The encryption version to use for the PushAPI. |
| - | options.versionMeta | { NFTPGP_V1 ?: password: string } | - | Metadata related to the encryption version, including a password if needed. |
| - | options.autoUpgrade | boolean | true | If true, upgrades encryption keys to latest encryption version. |
| - | options.origin | string | - | Specify origin or source while creating a Push Profile. |
Note: Parameters
in this styleare mandatory.
ProgressHook Type and Response
Informs about individual progress stages during user creation / updates if progresshook as a callback function is passed during API call.
| Param | Type | Subtype | Default | Remarks |
|---|---|---|---|---|
progress | object | - | - | progress object that is passed in the callback |
| - | Progress.progressId | string | - | Predefined, ID associated with the progress objects |
| - | Progress.progressTitle | string | - | Predefined, title associated with the progress objects |
| - | Progress.progressInfo | string | - | Predefined, info associated with the progress objects |
| - | Progress.level | string | - | Predefined, Level associated with the progress objects |
Progress object details
| Progress.id | Progress.level | Progress.title | Progress.info |
|---|---|---|---|
PUSH-CREATE-01 | INFO | Generating Secure Profile Signature | This step is only done for first time users and might take a few seconds. PGP keys are getting generated to provide you with secure yet seamless chat |
PUSH-CREATE-02 | INFO | Signing Generated Profile | This step is only done for first time users. Please sign the message to continue. |
PUSH-CREATE-03 | INFO | Encrypting Generated Profile | Encrypting your keys. Please sign the message to continue. |
PUSH-CREATE-04 | INFO | Syncing Generated Profile | Please sign the message to continue. Steady lads, chat is almost ready! |
PUSH-CREATE-05 | SUCCESS | Setup Complete | - |
PUSH-UPGRADE-01 | INFO | Deprecated Generating New Profile Signature | Trying to Upgrade Push Chat Keys to latest version. Please sign the message to continue. |
PUSH-UPGRADE-02 | INFO | Decrypting Old Profile | Trying to Upgrade Push Chat Keys to latest version. Please sign the message to continue. |
PUSH-UPGRADE-03 | INFO | Deprecated Syncing New Profile | Please sign the message to continue. Steady lads, chat is almost ready! |
PUSH-UPGRADE-04 | INFO | Deprecated Decrypting Old Profile | Trying to Upgrade Push Chat Keys to latest version. Please sign the message to continue. |
PUSH-UPGRADE-05 | SUCCESS | Upgrade Completed, Welcome to Push Chat | - |
PUSH-DECRYPT-01 | INFO | Decrypting Profile | Please sign the transaction to decrypt profile |
PUSH-DECRYPT-02 | SUCCESS | Push Profile Unlocked | Unlocking push profile |
PUSH-AUTH-UPDATE-01 | INFO | Generating New Profile Signature | Trying to Update Push Chat Keys to VERSION_NUMBER version. Please sign the message to continue. |
PUSH-AUTH-UPDATE-02 | INFO | Generating New Encrypted Profile | Encrypting Push Chat Keys with VERSION_NUMBER version. Please sign the message to continue. |
PUSH-AUTH-UPDATE-03 | INFO | Syncing Updated Profile | Please sign the message to continue. Steady lads, chat is almost ready! |
PUSH-AUTH-UPDATE-04 | SUCCESS | Update Completed, Welcome to Push Chat | - |
PUSH-AUTH-UPDATE-05 | INFO | Generating New Profile Signature | Trying to Update Push Profile creds. Please sign the message to continue. |
PUSH-AUTH-UPDATE-06 | INFO | Generating New Profile Signature | Encrypting Push Chat Keys with new creds. Please sign the message to continue. |
PUSH-DECRYPT-AUTH-01 | INFO | Decrypting Profile Creds | Please sign the transaction to decrypt profile creds. |
PUSH-DECRYPT-AUTH-02 | INFO | Push Profile Creds Unlocked | Unlocking push profile creds |
PUSH-PROFILE-UPDATE-01 | ERROR | Syncing Updated Profile | Steady lads, your profile is getting a new look! |
PUSH-PROFILE-UPDATE-02 | SUCCESS | Profile Update Completed, Welcome to Push Chat | - |
PUSH-ERROR-00 | ERROR | Non Specific Error | Dynamic error in the following format: [Push SDK] - API - Error - API [functionName()] -: [Dynamic Error Info] |
PUSH-ERROR-01 | WARN | Upgrade Profile Failed | Dynamic warning in the following format: [Push SDK] - API - Error - API decryptPgpKey() -: [Dynamic Error Info] |
PUSH-ERROR-02 | ERROR | Transaction failed | Dynamic warning in the following format: [Push SDK] - Contract - Error - [Name] -: [Dynamic Error Info] |
Expected response
{
{
account: "0xC785989454C958eF0fD343e3E6DcCDf9893a5b02",
channel: Channel {
signer: JsonRpcSigner,
env: 'prod',
guestMode: true,
account: '0xC785989454C958eF0fD343e3E6DcCDf9893a5b02',
info: ƒ,
…
},
chat: Chat {
account: '0xC785989454C958eF0fD343e3E6DcCDf9893a5b02',
decryptedPgpPvtKey: '-----BEGIN PGP PRIVATE KEY BLOCK-----\n\nxcLYBGQRtHI…nYedYb\n=o4+2\n-----END PGP PRIVATE KEY BLOCK-----\n',
env: 'prod',
signer: JsonRpcSigner,
progressHook: undefined,
…
},
decryptedPgpPvtKey: "-----BEGIN PGP PRIVATE KEY BLOCK-----\n\n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\nJPYaDBOrwODHzX8INjnYedYb\n=o4+2\n-----END PGP PRIVATE KEY BLOCK-----\n",
encryption: Encryption {
account: '0xC785989454C958eF0fD343e3E6DcCDf9893a5b02',
decryptedPgpPvtKey: '-----BEGIN PGP PRIVATE KEY BLOCK-----\n\nxcLYBGQRtHI…nYedYb\n=o4+2\n-----END PGP PRIVATE KEY BLOCK-----\n',
pgpPublicKey: '-----BEGIN PGP PUBLIC KEY BLOCK-----\n\nxsBNBGQRtHIB…HnWGw==\n=h2rm\n-----END PGP PUBLIC KEY BLOCK-----\n',
env: 'prod',
signer: JsonRpcSigner,
…
},
env: "prod",
notification: Notification {
signer: JsonRpcSigner,
env: 'prod',
guestMode: true,
account: '0xC785989454C958eF0fD343e3E6DcCDf9893a5b02',
list: ƒ,
…
},
pgpPublicKey: "-----BEGIN PGP PUBLIC KEY BLOCK-----\n\nxsBNBGQRtHIBCADWGXf/Ir844r6xG4FIoprXLv8LaekzuEDT1pYckE4TQSub\n6y1pCCF/eMWvUePvWBAgX8cNdBQ96gxnOB0Kxu2wQTWqLQ0PrL9ggF0dNQcQ\nPbPghOOTWwO2h/TKNa9KrhkCh9m9zjQU9o8w4HxOOJ74t8T9OXqYMOXBMSOr\nVw2bnGQfSodZV7PTJUqmA7ap5JwbGcNP9t1/XH87f6HFSgPwgN5u9rgKAwhJ\nFwujZxSJv2IPRNzpDAq/r/C+fgofkV9/kwU3odsKNMJ+REfNOhDVo+nBLHAu\nTloMkc2WSLJDSu9j8sNZPVrpUaa1c7bbxX5fVTXzW+n2/L2xBkWSfy11ABEB\nAAHNAMLAigQQAQgAPgWCZBG0cgQLCQcICZApG4QIthENGgMVCAoEFgACAQIZ\nAQKbAwIeARYhBGgybFDK2EulZ5avyikbhAi2EQ0aAAA/JQf7B6cVf1OHFncZ\nA/XprZxLLyLbRG3l8nHi8Ujd8IVWavecgYbn0zKuRbHvfkNKKXRKYQ3eMpP8\ns1XRofybhl3J6D5eSPMnw4sxysfteNBoPrBZKFCnY4JFzEDGX7XFIFnJ4ZTU\ncmCp3p0OO86ES3rSG2esmcF/uGUOSf71PspNPKWPfFT4EkpMzYsN8khJv6zA\nqmwYKfz7lCpcef/Wr20kRSN641Z2ZzpVhPQYsVpjcIboVZvb2b1lPUw6v6um\n+c6r4ONgC8HQD8vaC8aozYay9OOf5aDRT0CE8hivurA59TE1akvHDLly4F1H\nIBdShArEO0P7iM2UDZ8enNAloMOM687ATQRkEbRyAQgA3E9cwruXEXB7AwM1\nMzs9I8f2BI4xV+CddArdexeC1w/8zI3pJUYjZU3QlyAmZs9CYqjWil4CYBXy\nke+D4WVg7htEU2DykCrW1pqW+YFIXdN5p6MLOYfPKW7EU4lq1bRC3AnKHa0g\nz5XrmrU89Z8PmcLVtXeAwHM5M/cnCjHQD3a9W4WiglBgYJCqhMoxNK587WRw\n6kqzCp6OVBGozGrrmr+Cjy8fbpmHyjzss/8984RTS14TrCS33cTdTbd52R6p\nAFK3WEDyiJxBfjyZ5UTZlwcpNR84cAWheRUg9RNgnBuOwclsdZdMonfMXsUy\nYJaQKJ4vIbdme1kr31uxVdn/9QARAQABwsB2BBgBCAAqBYJkEbRyCZApG4QI\nthENGgKbDBYhBGgybFDK2EulZ5avyikbhAi2EQ0aAACoYAf/ZjF6FfGDdUZn\nshJPYVTIlhy7w+cImozxHDGZWZah2bjddnJ8a4jedSa6oSYBeBP5vnvw7Smf\n5+CvwCrIQdzBlM1VyRWRdlP9e3QixTCqDgfyUVKRavYYgH8l9MFAw57Bq8Y+\nsckgDkY7A04cYvd93SCclwGC4X9GshnBYgbjPbAqOSPBhq1i+i1R+zYGqy92\nPGxT83rgjJiXIjhiVxZCzZVy+X8KU58nQLIbWj2zR0xgO7oMnaZFOMYtHtoe\nmCIq58+IQt7ETENsqYKR5u+f6ep5+pF0vtvZBDp2DVVMvoabUW5AP31NsFdG\nwUJaHST2GgwTq8Dgx81/CDY52HnWGw==\n=h2rm\n-----END PGP PUBLIC KEY BLOCK-----\n",
profile: Profile {
account: '0xC785989454C958eF0fD343e3E6DcCDf9893a5b02',
decryptedPgpPvtKey: '-----BEGIN PGP PRIVATE KEY BLOCK-----\n\nxcLYBGQRtHI…nYedYb\n=o4+2\n-----END PGP PRIVATE KEY BLOCK-----\n',
env: 'prod',
progressHook: undefined
},
progressHook: undefined,
signer: JsonRpcSigner {
_isSigner: true,
provider: Web3Provider,
_index: 0,
_address: null
},
user: User {
account: '0xC785989454C958eF0fD343e3E6DcCDf9893a5b02',
env: 'prod'
},
}
}
Initialize user interface
/**
* Initialization Parameters for PushAPI
*/
/**
* Specifies the type of signer.
* Choose between Ethers or Viem Signer.
*/
type Signer = SignerType;
interface PushAPIInitializeProps {
/**
* Sets the API environment.
* Options: 'prod', 'staging', 'dev'
* Default: 'staging'
*/
env?: ENV;
/**
* A callback function to receive updates during the initialization process.
*/
progressHook?: (progress: ProgressHookType) => void;
/**
* The account you want to link with the PushAPI.
* If left empty, it'll use the account associated with your signer.
*/
account?: string;
/**
* Specifies the encryption version for the PushAPI.
* Default: 'ENC_TYPE_V3'
*/
version?: string;
/**
* Provides additional data related to your chosen encryption version,
* like a necessary password.
*/
versionMeta?: {
NFTPGP_V1?: {
password: string;
};
};
/**
* When set to true, the system will automatically upgrade encryption keys
* to the latest available encryption version.
* Default: true
*/
autoUpgrade?: boolean;
/**
* Defines the origin or source when setting up a Push Profile.
*/
origin?: string;
}
/**
* Initializes the PushAPI with given parameters.
*
* @param signer The type of signer (Ethers or Viem Signer).
* @param options Optional configurations for initializing the PushAPI.
*/
function initializePushAPI(signer: Signer, options?: PushAPIInitializeProps) {
// Initialization logic here
}
Reinitialize user API
- js
// Reinitialize PushAPI for fresh start of NFT Account
// Reinitialize only succeeds if the signer account is the owner of the NFT
// PushAPI.reinitialize{options?});
await userAlice.reinitialize({
versionMeta: { NFTPGP_V1: { password: 'NewPassword' } },
});
The function resets the Push NFT user profile including all connections and communication. It's important to note that this method is not applicable to standard wallet addresses.
This is particularly useful during instances of NFT transfers where the NFT user password is not shared as it completely resets all communications, acting as a fresh start.
Important - If the NFT user password is shared, then do not to use this method, instead you should look at User encryption update API for managing user migration.
Reinitialize user parameters
| Param | Type | Sub-Type | Default | Remarks |
|---|---|---|---|---|
options | PushAPIReinitializeProps | - | - | Optional configuration properties for reinitializing the PushAPI NFT account. |
| - | options.versionMeta | { NFTPGP_V1 : password: string } | - | Metadata related to the nft encryption version, including a password need for encrypting NFT account |
Note: Parameters
in this styleare mandatory.