Skip to main content

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

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:

ParamTypeSub-TypeDefaultRemarks
signerSignerType--Ethers or Viem Signer. Pass null and provide account to enable read only mode
optionsPushAPIInitializeProps--Optional configuration properties for initializing the PushAPI.
-options.envENVstagingAPI 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.accountstring-The account to associate user with. If not provided, it is derived from signer.
-options.versionstringENC_TYPE_V3The 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.autoUpgradebooleantrueIf true, upgrades encryption keys to latest encryption version.
-options.originstring-Specify origin or source while creating a Push Profile.

Note: Parameters in this style are 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.

ParamTypeSubtypeDefaultRemarks
progressobject--progress object that is passed in the callback
-Progress.progressIdstring-Predefined, ID associated with the progress objects
-Progress.progressTitlestring-Predefined, title associated with the progress objects
-Progress.progressInfostring-Predefined, info associated with the progress objects
-Progress.levelstring-Predefined, Level associated with the progress objects

Progress object details

Progress.idProgress.levelProgress.titleProgress.info
PUSH-CREATE-01INFOGenerating Secure Profile SignatureThis 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-02INFOSigning Generated ProfileThis step is only done for first time users. Please sign the message to continue.
PUSH-CREATE-03INFOEncrypting Generated ProfileEncrypting your keys. Please sign the message to continue.
PUSH-CREATE-04INFOSyncing Generated ProfilePlease sign the message to continue. Steady lads, chat is almost ready!
PUSH-CREATE-05SUCCESSSetup Complete-
PUSH-UPGRADE-01INFODeprecated Generating New Profile SignatureTrying to Upgrade Push Chat Keys to latest version. Please sign the message to continue.
PUSH-UPGRADE-02INFODecrypting Old ProfileTrying to Upgrade Push Chat Keys to latest version. Please sign the message to continue.
PUSH-UPGRADE-03INFODeprecated Syncing New ProfilePlease sign the message to continue. Steady lads, chat is almost ready!
PUSH-UPGRADE-04INFODeprecated Decrypting Old ProfileTrying to Upgrade Push Chat Keys to latest version. Please sign the message to continue.
PUSH-UPGRADE-05SUCCESSUpgrade Completed, Welcome to Push Chat-
PUSH-DECRYPT-01INFODecrypting ProfilePlease sign the transaction to decrypt profile
PUSH-DECRYPT-02SUCCESSPush Profile UnlockedUnlocking push profile
PUSH-AUTH-UPDATE-01INFOGenerating New Profile SignatureTrying to Update Push Chat Keys to VERSION_NUMBER version. Please sign the message to continue.
PUSH-AUTH-UPDATE-02INFOGenerating New Encrypted ProfileEncrypting Push Chat Keys with VERSION_NUMBER version. Please sign the message to continue.
PUSH-AUTH-UPDATE-03INFOSyncing Updated ProfilePlease sign the message to continue. Steady lads, chat is almost ready!
PUSH-AUTH-UPDATE-04SUCCESSUpdate Completed, Welcome to Push Chat-
PUSH-AUTH-UPDATE-05INFOGenerating New Profile SignatureTrying to Update Push Profile creds. Please sign the message to continue.
PUSH-AUTH-UPDATE-06INFOGenerating New Profile SignatureEncrypting Push Chat Keys with new creds. Please sign the message to continue.
PUSH-DECRYPT-AUTH-01INFODecrypting Profile CredsPlease sign the transaction to decrypt profile creds.
PUSH-DECRYPT-AUTH-02INFOPush Profile Creds UnlockedUnlocking push profile creds
PUSH-PROFILE-UPDATE-01ERRORSyncing Updated ProfileSteady lads, your profile is getting a new look!
PUSH-PROFILE-UPDATE-02SUCCESSProfile Update Completed, Welcome to Push Chat-
PUSH-ERROR-00ERRORNon Specific ErrorDynamic error in the following format: [Push SDK] - API - Error - API [functionName()] -: [Dynamic Error Info]
PUSH-ERROR-01WARNUpgrade Profile FailedDynamic warning in the following format: [Push SDK] - API - Error - API decryptPgpKey() -: [Dynamic Error Info]
PUSH-ERROR-02ERRORTransaction failedDynamic 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

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

ParamTypeSub-TypeDefaultRemarks
optionsPushAPIReinitializeProps--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 style are mandatory.