Cloud API Local Storage

Cloud API Local Storage gives you the option to control where your message data is stored at rest. If your company is in a regulated industry such as finance, government, or healthcare, you may prefer to have your message data stored in a specific country when at rest because of regulatory or company policies.

Cloud API Local Storage provides such an extra layer of data protection by implementing additional data management controls. Local Storage feature comprises of two additional constraints in Cloud API runtime environment:

• Data-in-use TTL (Time-to-Live): A new data retention constraint is implemented, enforcing how long message content is accessible to Cloud API on Meta data centers outside the target jurisdiction while being processed. When using Local Storage, Cloud API will automatically delete message content from Meta data centers after a TTL of 60 minutes. There will be no message content on Meta servers outside the target jurisdiction after the TTL when using local storage.
• Data-at-rest location: A new data placement constraint is implemented, enforcing which physical location Cloud API is allowed to use as a persistent storage for message content. Text and media payload of both incoming and outgoing messages will be stored in the Cloud API in-country (non-US) data stores.

Once Local Storage is enabled for a business phone number, Cloud API Local Storage uses a localized storage in the specified country for persisting message content, instead of using its default storage based in the US.

Local Storage feature supplements other Cloud API privacy and security controls, and allows customers to ensure a higher level of compliance with local data protection regulations.

Localized Data

Cloud API implements localization for message content. The following message flows are covered by Local Storage feature:

• Outgoing messages: messages you are sending to recipients via Cloud API
• Incoming messages: messages you are receiving back via Cloud API

The following message types are covered by Local Storage feature:

• Text messages: textual payload (message body) is localized
• Media messages: media (audio, document image or video) payload is localized
• Template messages: components with text / media payload are localized

Also, a limited set of metadata attributes is included in the localized data set, in order to correctly associate the encrypted localized message payload with the originally processed message and to audit the fact of localization. The stored metadata is protected with tokenization and encryption.

The goal of Cloud API Local Storage feature is to allow your business to directly control where your sensitive data-at-rest is stored via Cloud API settings - at the same time giving you flexibility to choose data placement locations globally.

Available Regions

The regions permitted by Cloud API Local Storage are reflected in the Meta Hosting Terms for Cloud API. The regions currently available for Local Storage can be found under the data_localization_region parameter set during phone number registration.

Requirements

Local Storage can only be enabled or disabled on business phone numbers when they are in an unregistered state.

Limitations

Media files uploaded by a phone number with Local Storage enabled are only accessible to that specific phone number and cannot be shared with other phone numbers associated with the business.

Enabling Local Storage

Follow the steps below to enable local storage for an unregistered business phone number using API version 21.0 or newer. If you are using an older API version, see Enabling Local Storage (v20 and older).

Step 1: Enable local storage on the number

Use the POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/settings endpoint to enable local storage on the unregistered business phone number:

Request Syntax

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/settings

{
  "storage_configuration": {
    "status": "IN_COUNTRY_STORAGE_ENABLED", 
    "data_localization_region": "<COUNTRY_CODE>"
  }
}

Set <COUNTRY_CODE> to the country code of the country where data-at-rest should be stored.

Response Syntax

{
  "success": <SUCCESS>
}

Upon success, <SUCCESS> will be set to true.

Example Request

curl 'https://graph.facebook.com/v21.0/106540352242922/settings' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "storage_configuration": {
    "status": "IN_COUNTRY_STORAGE_ENABLED", 
    "data_localization_region": "BR"
  }
}'

Example Response

{
  "success": true
}

Step 2: Register the number

Use the POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/register endpoint to register the business phone number.

Request Syntax

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/register

{
  "messaging_product": "whatsapp",
  "pin": "<TWO_STEP_PIN>"
}

Set <TWO_STEP_PIN> to the desired two-step verification PIN for the business phone number.

Response Syntax

{
  "success": <SUCCESS>
}

Upon success, <SUCCESS> will be set to true.

Example Request

curl 'https://graph.facebook.com/v21.0/v21.0/register' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "pin": "123456"
}'

Example Response

{
  "success": true
}

Getting Local Storage Settings

Use the GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/settings endpoint to get local storage settings on a WhatsApp Business Phone Number. For example:

curl 'https://graph.facebook.com/v21.0/179776755229976/settings' \
-H 'Authorization: Bearer EAAJB...'

This returns a node that represents the local storage settings on the business phone number. For example:

{
  "storage_configuration": {
    "status": "IN_COUNTRY_STORAGE_ENABLED",
    "data_localization_region": "BR"
  }
}

Disabling Local Storage

Use the POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/settings endpoint to disable local storage on an unregistered business phone number using API version 21.0 or newer. If you are using an older API version, see Disabling Local Storage (v20 and older).

Request Syntax

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID/>settings

{
  "storage_configuration": {
    "status": "IN_COUNTRY_STORAGE_DISABLED"
  }
}

Set <COUNTRY_CODE> to the country code of the country where data-at-rest should be stored.

Response Syntax

{
  "success": <SUCCESS>
}

Upon success, <SUCCESS> will be set to true.

Example Request

curl 'https://graph.facebook.com/v21.0/106540352242922/settings' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "storage_configuration": {
    "status": "IN_COUNTRY_STORAGE_DISABLED"
  }
}'

Example Response

{
  "success": true
}

Enabling Local Storage (v20 and older)

To enable local storage for an unregistered business phone number using API version 20.0 or older):

Step 1: Check verification status

Use the GET /<WHATSAPP_BUSINESS_PHONE_NUMBER> endpoint and request the code_verification_status field. If the code verification status is VERIFIED, skip to step 4. Otherwise, proceed to step 2.

Step 2: Request a verification code

Use the POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/request_code endpoint to request a verification code. Upon success, the API will respond with true and a verification code will be sent to the business phone number via the method specified in the code_method parameter.

For example, this query requests a verification code to be sent via SMS in the English language (US locale).

curl -X POST 'https://graph.facebook.com/v21.0/110200345501442/request_code?code_method=SMS&language=en_US' \
-H 'Authorization: Bearer EAAJB...'

Use the code in the delivered message in the next step.

Step 3: Verify the business phone number

Use the POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/verify_code endpoint to verify the business phone number using the verification code included in the message you received from the previous step.

For example:

curl -X POST 'https://graph.facebook.com/v21.0/110200345501442/verify_code?code=123830' \
-H 'Authorization: Bearer EAAJB...'

Step 4: Reregister the business phone number

Use the POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/register endpoint to register the business phone number. Indicate the country where data-at-rest should be stored using the data_localization_region parameter.

For example, this request enables local storage on a business phone number, and sets the country where data should be stored to India:

curl 'https://graph.facebook.com/v21.0/110200345501442/register' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "pin": "123456",
  "data_localization_region": "IN"
}'

Disabling Local Storage (v20 and older)

Use the POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/deregister endpoint to disable local storage on a business phone number using API version 20.0 or older.

For example:

curl -X POST 'https://graph.facebook.com/v21.0/110200345501442/deregister' \
-H 'Authorization: Bearer EAAJB...'

Note that this deregisters the business phone number so it cannot be used with WhatsApp Cloud API. If you want to continue using it with Cloud API but without local storage enabled, you must reregister it without including the data_localization_region parameter.

FAQs

Q. What are the migration paths for moving a phone number to the Cloud API version with Local Storage?

We support all migration paths to Cloud API version with Local Storage, this includes:

• Existing On-Premise API number migrating to Cloud API version with Local Storage
• Existing Cloud API number migrating to Cloud API version with Local Storage
• New Cloud API number enabling Local Storage

In all these scenarios you would need to send a POST request to the /register endpoint for the selected phone number, specifying the target country for which data to be localized in a new parameter data_localization_region.

Q. Are there any migration risks? Any downtime associated with this?

No migration risks, this is a similar process as migrating from On-Premise API to Cloud API. See our developer documentation here. Downtime is typically less than 5 minutes and no re-verification of the business phone number is required.