Backup and Restore Settings

/v1/settings

Use the /v1/settings/backup and /v1/settings/restore endpoints to make it easier to move to different environments or servers and restore to a known working state. We recommend that you back up occasionally so that if your WhatsApp Business API client or server goes down, you can easily bring it back up.

The WhatsApp Business API client supports backing up and restoring all necessary information including:

App settings
Registration

Note: The backup will not back up messages or callbacks, and taking virtual machine snapshots and restoring them will not work.

You must use the admin account to access the backup and restore settings.

Security Update

In v2.31.4 WhatsApp fixed the backup and restore endpoints to make them consistent with the security model of the backup and restore functionality of other WhatsApp clients (i.e., phone apps). With this change a new security code will be generated between your WhatsApp business account and its contacts after a successful restore operation.

After a WhatsApp business account restores from backup, the consumer client will receive a notice “Your security code with {Business Account} changed. Tap to learn more.” if they have the “security notification” setting enabled. All other backup/restore behaviors remain the same as before.

Backing up (Export)

The ability to back up/export only runs after the WhatsApp Business API Client has been registered and is running.

Request

To back up, use the /v1/settings/backup endpoint with the password field.

POST /v1/settings/backup
{
    "password": "your-password"
}

Parameters

Name	Type	Description
`password`	String	Used to encrypt backup data for security

Response

{
    "settings": {
       "data": "encrypted-backup-data"
    }
}

Parameters

Name	Type	Description
`settings`	String	The `settings` object containing the `data` element
`data`	String	The data that has been backed up, encrypted for security.

Save the data value as that will be used along with your password to restore the information.

Restoring (Import)

Restore can be used to set up a new version of the WhatsApp Business API Client on a new machine or restore the application to a known working state on the same machine with the same encryption information and settings of a previous setup.

For setting up the application on a new machine, the Coreapp must be running, but not registered. Upon successful import, the Coreapp will automatically initialize itself and start serving requests. If the machine has an existing application and you do a restore, the application will stop and you will have to start it again with the docker restart command.

When restoring a multiconnect setup, you need to perform the restore on top of the same type of setup you are restoring from. For example, if you backed up a setup with two shards running, you must have two shards running for the restore.

Request

To restore settings, use the /v1/settings/restore endpoint with the password and data fields.

POST /v1/settings/restore
{
    "password": "your-password",
    "data": "your-encrypted-backup-data"
}

The WhatsApp Business API Client will shutdown after import. In certain deployments (e.g., AWS) the application will restart automatically. Otherwise, you will have to restart the service using the docker restart command.

Parameters

Name	Type	Description
`password`	String	The password you used in the `/v1/settings/backup` API call to encrypt the backup data
`data`	String	The data that was returned by the `/v1/settings/backup` API call

Response

A successful request returns the HTTP Status Code 200 OK and either null or {}.

If you encounter any errors, see Error and Status Messages.