API de Nuvem

Armazenamento Local da API de Nuvem

Com o Armazenamento Local da API de Nuvem, é possível controlar onde os dados de mensagens são armazenados em repouso. Caso sua empresa seja de um setor regulamentado (como finanças, organizações governamentais ou serviços de saúde), talvez você prefira que os dados em repouso das mensagens sejam armazenados em um país específico devido às políticas regulatórias ou da empresa.

O Armazenamento Local da API de Nuvem fornece uma camada extra de proteção de dados ao implementar diferentes controles de gerenciamento de informações. O recurso de Armazenamento Local possui duas restrições adicionais no ambiente de execução da API de Nuvem:

  • Tempo de vida (TTL, pelas inicias em inglês) de dados em uso: uma nova restrição de retenção de dados impõe um período de tempo durante o qual o conteúdo de mensagens fica acessível à API de Nuvem nos data centers da Meta fora da jurisdição durante o processamento. Ao usar o Armazenamento Local, a API de Nuvem excluirá automaticamente o conteúdo de mensagens dos data centers da Meta após um TTL de 60 minutos. Isso significa que não haverá conteúdo de mensagens em servidores da Meta fora da jurisdição após o TTL.
  • Localização de dados em repouso: uma nova restrição de posicionamento de dados impõe a localização física que pode ser usada pela API de Nuvem como armazenamento persistente para conteúdo de mensagens. A carga de mídia e texto das mensagens recebidas/enviadas será armazenada em repositórios de dados da API de Nuvem localizados no país (fora dos EUA).

Depois que o Armazenamento Local é habilitado para um número de telefone comercial, a API de Nuvem armazena o conteúdo persistente de mensagens no país especificado, em vez de usar o armazenamento padrão baseado nos EUA.

O Armazenamento Local complementa outros controles de privacidade e segurança da API de Nuvem e permite que os clientes garantam a conformidade com regulamentos locais de proteção de dados.

Dados localizados

A API de Nuvem implementa a localização do conteúdo das mensagens. Os seguintes fluxos de mensagens estão incluídos no recurso de Armazenamento Local:

  • Mensagens de saída: mensagens sendo enviadas aos destinatários via API de Nuvem.
  • Mensagens recebidas: mensagens sendo recebidas via API de Nuvem.

Os seguintes tipos de mensagem estão incluídos no recurso de Armazenamento Local:

  • Mensagens de texto: carga textual (corpo da mensagem) é localizada.
  • Mensagens de mídia: a carga de mídia (áudio, documento, imagem ou vídeo) é localizada.
  • Mensagens de modelo: os componentes com carga de texto/mídia são localizados.

Além disso, um grupo limitado de atributos de metadados é incluído no conjunto de dados localizados. Assim, é possível associar a carga da mensagem localizada criptografada à mensagem originalmente processada e auditar a localização. Os metadados armazenados são protegidos com tokens e criptografia.

O objetivo do Armazenamento Local da API de Nuvem é permitir que a empresa controle onde os dados sensíveis serão armazenados nas configurações da API. Isso também oferece flexibilidade para escolher localizações de dados em todo o mundo.

Regiões disponíveis

Para ver as regiões permitidas pelo Armazenamento Local da API de Nuvem, leia o documento Meta Hosting Terms for Cloud API. No momento, as regiões disponíveis podem ser encontradas no parâmetro data_localization_regiondefinido durante o registro do número de telefone.

Requisitos

O recurso de Armazenamento Local só poderá ser habilitado ou desabilitado em números de telefone comercial que estiverem em um estado não registrado.

Limitações

Os arquivos de mídia enviados por um número de telefone com Armazenamento Local habilitado só poderão ser acessados ​​por esse número de telefone específico e não poderão ser compartilhados com outros números associados à empresa.

Como habilitar o Armazenamento Local

Siga as etapas abaixo para habilitar o Armazenamento Local em um número de telefone comercial não registrado usando a versão 21.0 ou mais recente da API. Se estiver usando uma versão mais antiga da API, consulte Como habilitar o Armazenamento Local (v20 e versões anteriores).

Etapa 1: habilitar o Armazenamento Local no número de telefone

Use o ponto de extremidade POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/settings para habilitar o Armazenamento Local no número de telefone comercial não registrado:

Sintaxe da solicitação

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/settings

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

Defina <COUNTRY_CODE> como o código do país do local onde os dados em repouso devem ser armazenados.

Sintaxe da resposta

{
  "success": <SUCCESS>
}

Em caso de sucesso, <SUCCESS> será definido como true.

Exemplo de solicitação

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"
  }
}'

Exemplo de resposta

{
  "success": true
}

Etapa 2: registrar o número de telefone

Use o ponto de extremidade POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/register para registrar o número de telefone comercial.

Sintaxe da solicitação

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/register

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

Defina <TWO_STEP_PIN> como o PIN de confirmação em duas etapas desejado para o número de telefone comercial.

Sintaxe da resposta

{
  "success": <SUCCESS>
}

Em caso de sucesso, <SUCCESS> será definido como true.

Exemplo de solicitação

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"
}'

Exemplo de resposta

{
  "success": true
}

Como obter as configurações do Armazenamento Local

Use o ponto de extremidade GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/settings para obter as configurações de armazenamento local em um número de telefone do WhatsApp Business. Por exemplo:

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

Isso retornará um nó que representa as configurações de armazenamento local no número de telefone comercial. Por exemplo:

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

Como desabilitar o Armazenamento Local

Use o ponto de extremidade POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/settings para desabilitar o Armazenamento Local em um número de telefone comercial não registrado com a versão 21.0 ou mais recente da API. Se estiver usando uma versão mais antiga da API, consulte Como desabilitar o Armazenamento Local (v20 e versões anteriores).

Sintaxe da solicitação

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID/>settings

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

Defina <COUNTRY_CODE> como o código do país do local onde os dados em repouso devem ser armazenados.

Sintaxe da resposta

{
  "success": <SUCCESS>
}

Em caso de sucesso, <SUCCESS> será definido como true.

Exemplo de solicitação

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"
  }
}'

Exemplo de resposta

{
  "success": true
}

Como habilitar o Armazenamento Local (v20 e versões anteriores)

Para habilitar o Armazenamento Local em um número de telefone comercial não registrado usando a v20.0 ou versões anteriores da API:

Etapa 1: consultar o status de verificação

Use o ponto de extremidade GET /<WHATSAPP_BUSINESS_PHONE_NUMBER> e solicite o campo code_verification_status. Se o status de verificação de código for VERIFIED, pule para etapa 4. Caso contrário, prossiga para a etapa 2.

Etapa 2: solicitar um código de verificação

Use o ponto de extremidade POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/request_code para solicitar um código de verificação. Em caso de sucesso, a API responderá com true, e um código de verificação será enviado ao número de telefone comercial por meio do método especificado no parâmetro code_method.

Por exemplo, esta consulta solicita que um código de verificação seja enviado via SMS em inglês (localidade nos EUA).

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

Use o código na mensagem entregue na próxima etapa.

Etapa 3: verificar o número de telefone comercial

Use o ponto de extremidade POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/verify_code para verificar o número de telefone comercial utilizando o código incluído na mensagem que você recebeu na etapa anterior.

Por exemplo:

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

Etapa 4: registrar o número de telefone comercial

Use o ponto de extremidade POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/register para registrar o número de telefone comercial. Indique o país onde os dados em repouso devem ser armazenados usando o parâmetro data_localization_region.

Esta solicitação habilita o Armazenamento Local em um número de telefone comercial e define o país onde os dados devem ser armazenados (por exemplo, Índia):

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"
}'

Como desabilitar o Armazenamento Local (v20 e versões anteriores)

Use o ponto de extremidade POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/deregister para desabilitar o Armazenamento Local em um número de telefone comercial com a v20.0 ou versões anteriores da API.

Por exemplo:

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

Vale ressaltar que isso cancelará o registro do número de telefone comercial e impedirá o uso dele com a API de Nuvem do WhatsApp. Se quiser continuar usando o número com a API de Nuvem, mas sem o Armazenamento Local habilitado, você deverá registrá-lo novamente sem incluir o parâmetro data_localization_region.

Perguntas frequentes

P. Quais são os caminhos de migração para mover um número de telefone para a versão da API de Nuvem com Armazenamento Local?

Aceitamos todos os caminhos de migração para a versão da API de Nuvem com Armazenamento Local, incluindo:

  • Migrar um número existente da API Local para a versão da API de Nuvem com Armazenamento Local
  • Migrar um número existente da API de Nuvem para a versão com Armazenamento Local
  • Habilitar um número novo na API de Nuvem com Armazenamento Local

Em todos esses casos, é necessário enviar uma solicitação POST ao ponto de extremidade /register para o número de telefone selecionado, especificando o país no qual os dados devem ser localizados em um novo parâmetro data_localization_region.

P. A migração traz algum risco? Haverá um período de inatividade?

Não existem riscos. Esse processo é semelhante ao da migração da API Local para a API de Nuvem. Consulte Como migrar da API Local para a API de Nuvem. Normalmente, o tempo de inatividade é inferior a 5 minutos, e não é preciso verificar o número de telefone comercial novamente.