Migrazione dall'API On-Premises all'API Cloud

Questo documento spiega come eseguire la migrazione dei numeri di telefono aziendali dall'API On-Premises all'API Cloud.

Tieni presente che la migrazione di un numero di telefono aziendale da un'API all'altra non è come la migrazione di un numero da un account WhatsApp Business (WABA) ad un altro.

Per migrare dall'API Cloud all'API On-Premises, consulta Migrazione dall'API Cloud all'API On-Premises.

Come funziona

Il processo di migrazione prevede la generazione di metadati sul numero di telefono aziendale, quindi l'utilizzo di quei dati per registrare il numero da utilizzare con l'API Cloud. Questa operazione determina l'annullamento della registrazione del numero sull'API On-Premises, poiché un numero può essere registrato per l'utilizzo solo con un'API alla volta.

La migrazione NON ha effetto sugli elementi seguenti:

• il nome visualizzato del numero di telefono aziendale, lo stato della verifica o la valutazione della qualità;
• i modelli usati dal numero di telefono aziendale o il loro stato;
• l'account WhatsApp Business proprietario, il suo stato di account business ufficiale o il suo limite di messaggi.

Tuttavia, per supportare la migrazione, devi essere a conoscenza di eventuali differenze nelle API e adottare le misure appropriate per affrontarle prima di eseguire le fasi di migrazione descritte in questo documento.

Requisiti

App Meta

Devi avere un'app business di Meta che sia in grado di usare l'API Cloud e l'API Business Management con i dati dei clienti registrati e che sia in grado di integrare i webhook dell'API Cloud e dell'API Business Management. L'app deve anche essere associata a o reclamata dal tuo account business di Meta verificato.

Se non hai un'app business di Meta o se ne hai una ma non hai configurato il prodotto WhatsApp su di essa, completa i passaggi riportati nella nostra guida Primi passi dell'API Cloud. Completando questi passaggi, genererai tutti gli asset necessari per testare l'API Cloud e l'API Business Management.

Analisi dell'app

La tua app di Meta deve essere sottoposta all'analisi dell'app ed essere approvata (ovvero, avere accesso avanzato) per le autorizzazioni whatsapp_business_messaging e whatsapp_business_management.

Best practice

Dopo aver verificato che la tua app possa gestire tutte le differenze nelle API, ti consigliamo di eseguire prima la migrazione di un numero di telefono aziendale con volumi ridotti e verificare che tutte le funzionalità che intendi offrire con l'API Cloud funzionino correttamente. Dopo aver verificato che tutto funziona correttamente, esegui la migrazione di numeri aggiuntivi.

Ti consigliamo inoltre di effettuare la migrazione quando il traffico verso la distribuzione dell'API On-Premises è basso.

Differenze nelle API

Le seguenti funzioni dell'API On-Premises non sono supportate o sono trattate in modo diverso dall'API Cloud. Assicurati che la tua app sia in grado di gestire queste differenze prima di iniziare la migrazione.

Webhook

Le strutture payload dei webhook dell'API Cloud e dell'API Business Management sono diverse dalle strutture payload dell'API On-Premises. Ti consigliamo di creare un nuovo endpoint webhook che possa gestire esclusivamente l'API Cloud e l'API Business Management.

Consulta la documentazione seguente per comprendere le differenze di payload e come configurare i webhook sulla tua app usando la Dashboard gestione app:

• Configurazione: Webhook per WhatsApp
• Payload webhook API Cloud: Riferimento al payload delle notifiche dei webhook
• Payload webhook API Business Management: Configurazione webhook

Dopo aver eseguito la migrazione di un numero di telefono aziendale all'API Cloud, devi usare l'endpoint Account WhatsApp Business > App iscritte per iscrivere la tua app di Meta ai webhook sull'account WhatsApp Business associato al numero aziendale:

Sintassi della richiesta

curl -X POST 'https://graph.facebook.com/v17.0/<WABA_ID>/subscribed_apps' \
-H 'Authorization: Bearer EAAJB...'

Una volta completata la migrazione all'API Cloud, la consegna dei webhook dell'API On-Premises del numero di telefono aziendale sarà interrotta e inizierà quella dei webhook dell'API Cloud.

Contenuti multimediali

Gli ID di qualsiasi contenuto multimediale caricato nell'API On-Premises non possono essere usati quando si inviano messaggi con l'API Cloud, quindi devi ricaricare il contenuto multimediale usando l'API Cloud per generare nuovi ID oppure usare gli URL dei contenuti multimediali se tali contenuti sono ospitati su un server pubblico. Consulta Messaggi multimediali e Modelli di messaggi basati su contenuto multimediale.

Per garantire l'integrità dei messaggi, alcuni domini di hosting di contenuti multimediali consentiti dall'API On-Premises non lo sono dall'API Cloud. Se usi un servizio di hosting per i tuoi contenuti multimediali, ti consigliamo di testare gli URL dei contenuti in messaggi liberi e modelli di messaggi prima della migrazione. Se ritieni che il tuo host sia bloccato per errore, contatta l'assistenza.

Codici di errore

I codici di errore dell'API Cloud e dell'API Business Management sono diversi dai codici di errore dell'API On-Premises. Consulta i documenti seguenti:

• Codici di errore dell'API Cloud
• Codici di errore dell'API Business Management

Convalida della proprietà

• L'API On-Premises può accettare proprietà sconosciute nei payload dei corpi dei messaggi, ma l'API Cloud rifiuterà queste richieste, quindi fai in modo che le tue richieste di invio di messaggi usino solo proprietà supportate.
• L'API On-Premises consente l'omissione di indici di pulsanti quando invii messaggi con un solo pulsante, ma l'API Cloud rifiuterà queste richieste, quindi assicurati che le richieste di invio di messaggi che includono pulsanti includano anche indici e relativi valori.
• L'API On-Premises accetta stringhe di testo che contengono spazi iniziali o finali (o solo spazi) sulle proprietà degli oggetti di azione e pulsante quando invii messaggi interattivi, ma l'API Cloud rifiuterà queste richieste.

Messaggi Premi per parlare

On-Premises identifica i messaggi Premi per parlare (push-to-talk, PTT) nei webhook impostando messages.type su voice, mentre l'API Cloud identifica i messaggi PTT impostando messages.audio.voice su true.

Pacchetti di adesivi

L'API Cloud non supporta i pacchetti di adesivi.

Tempo di inattività

Il tempo di inattività inizia non appena esegui il passaggio finale di migrazione (registrando il numero da usare con l'API Cloud) e dovrebbe durare solo pochi secondi. Durante questo periodo, i messaggi inviati al numero dagli utenti di WhatsApp verranno eliminati senza avvisare.

Ti consigliamo vivamente di programmare la migrazione in un periodo in cui il numero ha un'attività bassa, per ridurre al minimo l'impatto del tempo di inattività.

Throughput

Se il numero di telefono aziendale On-Premises ha multiconnect in esecuzione su 2 o più shard, verrà automaticamente aggiornato a throughput elevato sull'API Cloud.

Account business ufficiali

Se stai effettuando la migrazione di un numero di telefono aziendale con stato di account business ufficiale (OBA) , questo stato verrà mantenuto se ne includi i metadati (generati nel passaggio 2) al momento della registrazione del numero (passaggio 3). Se ometti questi dati, il numero perderà il suo status OBA.

Assistenza per la migrazione

Se hai domande o hai bisogno di aiuto per la migrazione, invia un ticket all'Assistenza diretta con:

• Argomento: WABiz: Cloud API (WhatsApp Business: API Cloud)
• Tipo di richiesta: On-Premises API -> Cloud API Migration Issues (Problemi di migrazione API On-Premises -> API Cloud)

Passaggio 1: disattivazione della verifica in due passaggi

Se conosci il PIN del numero di telefono aziendale, puoi saltare questo passaggio.

Avrai bisogno del PIN del numero di telefono aziendale quando esegui il passaggio 3, quindi se non conosci il PIN, devi prima disabilitare la verifica in due passaggi sul numero di telefono aziendale. Se non possiedi il numero di telefono aziendale, chiedi al proprietario di disabilitarlo.

Passaggio 2: generazione dei metadati del numero di telefono

Usa l'API Backup and Restore per generare metadati sul numero di telefono aziendale.

Sintassi della richiesta

POST /v1/settings/backup
{
  "password": "<PASSWORD>"
}

<PASSWORD> può essere qualsiasi stringa. Questo valore verrà usato per codificare i metadati, quindi tienine traccia perché ne avrai bisogno nel prossimo passaggio.

Risposta

{
  "settings": {
    "data": "<METADATA>"
  },
  "meta": {
    "api_status": "<API_STATUS>",
    "version": "<API_VERSION>"
  }
}

L'API restituirà una stringa codificata assegnata alla proprietà data che descrive il tuo numero di telefono aziendale e le relative impostazioni. Annota questo valore perché ti servirà nel prossimo passaggio.

• <METADATA>: questa è la stringa codificata che descrive il tuo numero di telefono aziendale e le relative impostazioni. Annota questo valore perché ti servirà nel prossimo passaggio.
• <API_STATUS>: lo stato dell'implementazione dell'API On-Premises.
• <API_VERSION>: il numero di versione dell'API On-Premises in esecuzione.

Esempio di richiesta

curl 'https://localhost:9090/v1/settings/backup' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "password": "tacocat"
}'

Esempio di risposta

{
  "settings": {
    "data": "V0FCS..."
  },
  "meta": {
    "api_status": "stable",
    "version": "2.49.3"
  }
}

Passaggio 3: registrazione del numero

Usa l'endpoint Numero di telefono WhatsApp Business > Registrati dell'API Cloud per registrare il numero da usare con l'API Cloud.

Includi il valore dei metadati del numero di telefono aziendale codificato e la password del passaggio precedente. Anche se puoi registrare il numero senza questi dati, i dati del profilo del numero di telefono aziendale andranno persi se non vengono inclusi e ciò può influire sullo stato dell'account WhatsApp Business come account business ufficiale.

Sintassi della richiesta

POST /<BUSINESS_PHONE_NUMBER_ID>/register

Corpo del post

{
  "messaging_product": "whatsapp",
  "pin": "<NEW_OR_EXISTING_PIN>",
  "backup": {
    "password": "<PASSWORD>",
    "data": "<METADATA>"
  }
}

• <NEW_OR_EXISTING_PIN>: il PIN esistente o il PIN che vuoi impostare sul numero di telefono aziendale.
• <PASSWORD>: la password che hai usato per generare i metadati del numero di telefono aziendale nel passaggio precedente.
• <METADATA>: la stringa codificata che descrive il tuo numero di telefono aziendale e le relative impostazioni, generata nel passaggio precedente.

Risposta

{
  "success": <SUCCESS>
}

L'API risponderà con success impostato su true se la registrazione è andata a buon fine o su false se è stato generato un errore.

Esempio di richiesta

curl 'https://graph.facebook.com/v19.0/110200345501442/register' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "pin": "134568",
  "backup": {
    "password": "tacocat",
    "data": "V0FCS..."
  }
}'

Esempio di risposta

{
  "success": true
}

Passaggio 4: controllo dello stato di integrità dei messaggi (facoltativo)

Richiedi il campo health_status sul numero di telefono aziendale e verifica che possa essere usato per i messaggi con l'API Cloud. Consulta Stato integrità messaggi.