API Cloud

Archiviazione locale dell'API Cloud

L'archiviazione locale dell'API Cloud consente di controllare dove memorizzare i dati dei tuoi messaggi a riposo. Se la tua azienda si muove in un settore regolamentato come finanza, governo o assistenza sanitaria, potresti preferire che i dati dei tuoi messaggi siano memorizzati in un determinato Paese, quando a riposo, in ragione di normative o politiche aziendali.

L'archiviazione locale dell'API Cloud offre questo tipo di livello extra di protezione dei dati implementando ulteriori controlli di gestione. La funzione Archiviazione locale presenta due vincoli aggiuntivi nell'ambiente runtime dell'API Cloud:

  • TTL (Time-to-Live) dati in uso: è implementato un nuovo vincolo di conservazione dei dati, che definisce per quanto tempo il contenuto dei messaggi è accessibile all'API Cloud sui data center di Meta al di fuori della giurisdizione di destinazione durante l'elaborazione. Quando usi la funzione Archiviazione locale, l'API Cloud eliminerà automaticamente i contenuti dei messaggi dai data center di Meta dopo un TTL di 60 minuti. Quando utilizzi l'archiviazione locale, non ci saranno contenuti dei messaggi sui server di Meta al di fuori della giurisdizione target dopo il TTL.
  • Posizione dati a riposo: è implementato un nuovo vincolo di posizionamento dati, che definisce la posizione fisica che l'API Cloud può usare come archivio permanente per i contenuti dei messaggi. Il payload di testo e contenuti multimediali dei messaggi in entrata e in uscita sarà memorizzato nei data store dell'API Cloud (non USA).

Quando l'archiviazione locale è abilitata per un numero di telefono aziendale, la funzione Archiviazione locale dell'API Cloud usa un archivio localizzato nel Paese specificato per i contenuti dei messaggi permanenti, anziché usare l'archivio predefinito negli Stati Uniti.

La funzione Archiviazione locale integra altri controlli di sicurezza e privacy dell'API Cloud e consente ai clienti di garantire un maggiore livello di conformità alle normative di protezione dei dati locali.

Dati localizzati

L'API Cloud implementa la localizzazione per i contenuti dei messaggi. La funzione Archiviazione locale si applica ai seguenti flussi di messaggi:

  • Messaggi in uscita: messaggi che invii ai destinatari tramite l'API Cloud
  • Messaggi in arrivo: messaggi che ricevi tramite l'API Cloud

La funzione Archiviazione locale si applica ai seguenti tipi di messaggi:

  • Messaggi di testo: il payload testuale (corpo del messaggio) è localizzato
  • Messaggi con contenuto multimediale: il payload del contenuto multimediale (audio, documento, immagine o video) è localizzato
  • Modelli di messaggi: i componenti con payload di testo/contenuti multimediali sono localizzati

Inoltre, nel set di dati localizzati è incluso un insieme limitato di attributi di metadati per associare correttamente il payload dei messaggi localizzati crittografati al messaggio originariamente elaborato e controllare la correttezza della localizzazione. I metadati memorizzati sono protetti con tokenizzazione e crittografia.

L'obiettivo della funzione Archiviazione locale dell'API Cloud è consentire alla tua azienda di controllare direttamente la posizione in cui i tuoi dati sensibili sono memorizzati, quando a riposo, tramite le impostazioni dell'API Cloud, dandoti allo stesso tempo flessibilità nella scelta dei luoghi di posizionamento dati a livello globale.

Aree geografiche disponibili

Le aree geografiche consentite dall'archiviazione locale dell'API Cloud sono riportate nelle Condizioni di hosting di Meta per l'API Cloud Le aree geografiche attualmente disponibili per l'archiviazione locale sono disponibili sotto il parametro data_localization_regionimpostato durante la registrazione del numero di telefono.

Requisiti

L'archiviazione locale può essere abilitata o disabilitata solo sui numeri di telefono aziendali quando non sono registrati.

Limitazioni

I file multimediali caricati da un numero di telefono con archiviazione locale abilitata sono accessibili solo a quel numero di telefono specifico e non possono essere condivisi con altri numeri di telefono associati all'azienda.

Abilitazione dell'archiviazione locale

Segui i passaggi riportati sotto per abilitare l'archiviazione locale per un numero di telefono aziendale non registrato usando la versione dell'API 21.0 o successiva. Se stai usando una versione precedente dell'API, consulta Abilitazione dell'archiviazione locale (v20 e versioni precedenti).

Passaggio 1: abilitazione dell'archiviazione locale sul numero

Usa l'endpoint POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/settings per abilitare l'archiviazione locale sul numero di telefono aziendale non registrato:

Sintassi della richiesta

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/settings

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

Imposta <COUNTRY_CODE> sul prefisso internazionale del Paese in cui devono essere archiviati i dati inattivi.

Sintassi della risposta

{
  "success": <SUCCESS>
}

In caso di azione eseguita correttamente, <SUCCESS> sarà impostato su true.

Esempio di richiesta

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

Esempio di risposta

{
  "success": true
}

Passaggio 2: registrazione del numero

Registra il numero di telefono aziendale usando l'endpoint POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/register.

Sintassi della richiesta

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/register

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

Imposta <TWO_STEP_PIN> sul PIN di verifica in due passaggi desiderato per il numero di telefono aziendale.

Sintassi della risposta

{
  "success": <SUCCESS>
}

In caso di azione eseguita correttamente, <SUCCESS> sarà impostato su true.

Esempio di richiesta

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

Esempio di risposta

{
  "success": true
}

Ottenere le impostazioni di archiviazione locale

Usa l'endoint GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/settings per ottenere le impostazioni di archiviazione locale su un numero di telefono WhatsApp Business. Ad esempio:

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

Viene restituito un nodo che rappresenta le impostazioni di archiviazione locale sul numero di telefono aziendale. Ad esempio:

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

Disabilitazione dell'archiviazione locale

Usa l'endpoint POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/settings per disabilitare l'archiviazione locale su un numero di telefono aziendale non registrato usando la versione dell'API 21.0 o successiva. Se stai usando una versione precedente dell'API, consulta Disabilitazione dell'archiviazione locale (v20 e versioni precedenti).

Sintassi della richiesta

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID/>settings

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

Imposta <COUNTRY_CODE> sul prefisso internazionale del Paese in cui devono essere archiviati i dati inattivi.

Sintassi della risposta

{
  "success": <SUCCESS>
}

In caso di azione eseguita correttamente, <SUCCESS> sarà impostato su true.

Esempio di richiesta

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

Esempio di risposta

{
  "success": true
}

Abilitazione dell'archiviazione locale (v20 e versioni precedenti)

Per abilitare l'archiviazione locale per un numero di telefono aziendale non registrato usando la versione dell'API 20.0 o precedente:

Passaggio 1: controlla lo stato della verifica

Usa l'endpoint GET /<WHATSAPP_BUSINESS_PHONE_NUMBER> e richiedi il campo code_verification_status. Se lo stato della verifica del codice è VERIFIED, vai al passaggio 4. In caso contrario, vai al passaggio 2.

Passaggio 2: richiedi un codice di verifica

Usa l'endpoint POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/request_code per richiedere un codice di verifica. Se l'operazione viene eseguita correttamente, l'API risponderà con true e un codice di verifica verrà inviato al numero di telefono aziendale tramite il metodo specificato nel parametro code_method.

Ad esempio, questa query richiede l'invio di un codice di verifica tramite SMS in lingua inglese (impostazioni internazionali USA).

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

Usa il codice nel messaggio consegnato nel passaggio successivo.

Passaggio 3: verifica il numero di telefono dell'azienda

Usa l'endpoint POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/verify_code per verificare il numero di telefono aziendale utilizzando il codice di verifica incluso nel messaggio che hai ricevuto al passaggio precedente.

Ad esempio:

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

Passaggio 4: registra di nuovo il numero di telefono dell'azienda

Registra il numero di telefono aziendale usando l'endpoint POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/register. Indica il Paese in cui i dati a riposo dovrebbero essere memorizzati utilizzando il parametro data_localization_region.

Ad esempio, questa richiesta consente l'archiviazione locale su un numero di telefono aziendale e imposta il Paese in cui i dati dovrebbero essere memorizzati in 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"
}'

Disabilitazione dell'archiviazione locale (v20 e versioni precedenti)

Usa l'endpoint POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/deregister per disabilitare l'archiviazione locale su un numero di telefono aziendale usando la versione dell'API 20.0 o precedente.

Ad esempio:

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

Tieni presente che quest'operazione annulla la registrazione del numero di telefono aziendale, che quindi non può essere usato con l'API Cloud di WhatsApp. Se vuoi continuare a usarlo con l'API Cloud ma senza l'archiviazione locale abilitata, devi registrarlo nuovamente senza includere il parametro data_localization_region.

FAQ

D. Quali sono i percorsi di migrazione per spostare un numero di telefono nella versione API Cloud con Archiviazione locale?

Supportiamo tutti i percorsi di migrazione alla versione API Cloud con Archiviazione locale, tra cui:

  • Il numero API On-Premise esistente che esegue la migrazione alla versione API Cloud con Archiviazione locale
  • Il numero dell'API Cloud esistente che esegue la migrazione alla versione API Cloud con Archiviazione locale
  • Il nuovo numero API Cloud che abilita la funzione Archiviazione locale

In tutti questi scenari dovresti inviare una richiesta POST all'endpoint /register per il numero di telefono selezionato, specificando il Paese di destinazione per cui i dati devono essere localizzati in un nuovo parametro data_localization_region.

D. Ci sono rischi correlati alla migrazione? Tempi di inattività?

Nessun rischio di migrazione, questo è un processo simile a quello della migrazione dall'API On-Premise all'API Cloud. Consulta la nostra documentazione per sviluppatori qui. Il tempo di inattività è solitamente inferiore a 5 minuti e non è necessario ripetere la verifica del numero di telefono aziendale.