Backup and Restore

/v1/settings/backup and /v1/settings/restore

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 and registration.

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

Before You Start

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

Backing Up

The ability to back up/export only runs after the WhatsApp Business API Client has been registered and is running. The backup does not back up messages or callbacks, and taking virtual machine snapshots and restoring them does not work.

Example

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

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

The response looks like this:

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

Parameters

Request parameters:

Response parameters:

Restoring

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 automatically initializes itself and starts serving requests. If the machine has an existing application and you do a restore, the application stops and you 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.

Example

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 shuts down after import. In certain deployments (e.g., AWS) the application restarts automatically. Otherwise, you have to restart the service using the docker restart command.

A successful request returns the HTTP Status Code 200 OK and either null or {}. If you encounter any errors, see Error and Status Messages.

Parameters