Migrazione dall'API Cloud all'API On-Premises

Questo documento spiega come eseguire la migrazione di numeri di telefono aziendali dall'API Cloud all'API On-Premises. Per effettuare la migrazione dall'API On-Premises all'API Cloud, consulta Migrazione 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) a un altro.

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.

Best practice

Dopo aver verificato che la tua app possa gestire tutte le differenze nelle API, ti consigliamo di effettuare prima la migrazione di un numero di telefono aziendale a basso volume e verificare che tutte le funzionalità che intendi offrire con l'API On-Premises funzionino correttamente. Dopo aver verificato che tutto funzioni correttamente, procedi con la migrazione dei numeri aggiuntivi.

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

Differenze nelle API

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 gestisca esclusivamente i webhook dell'API On-Premises.

Consulta i seguenti documenti per comprendere meglio le differenze di payload:

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

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

Contenuti multimediali

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

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

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.

Tempo di inattività

Il tempo di inattività inizia non appena esegui il passaggio di registrazione (passaggio 3) 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à.

Passaggio 1: integrazione dell'API On-Premises

Dal momento che stai migrando un numero di telefono aziendale all'API On-Premises, assicurati che la tua app possa utilizzare correttamente il client dell'API On-Premises e che nell'account WhatsApp Business associato al numero di telefono aziendale i webhook siano configurati correttamente.

Passaggio 2: preparazione alla migrazione

Ti consigliamo di interrompere l'invio di messaggi mentre completi la migrazione.

Il client On-Premises dell'API di WhatsApp Business prevede specifici requisiti di rete per la connessione ai server WhatsApp. Per assicurarti che sia tutto pronto, consulta Configurazione ed esecuzione del debug della rete.

Passaggio 3: registrazione del client dell'API

Registra il numero di telefono aziendale sul client dell'API On-Premises. Per farlo, chiama l'endpoint /account:

POST /v1/account

{
    "cc": "COUNTRY_CODE",
    "phone_number": "PHONE_NUMBER_WITHOUT_COUNTRY_CODE",
    "method": "sms" or "voice",
    "cert": "VERIFIED_NAME_CERT_IN_BASE64",
    "pin": "EXISTING_6_DIGIT_PIN" # required if two-step verification is enabled
}

Puoi consultare tutti i campi disponibili per questo endpoint qui.

Una volta completata la registrazione, sarà il client dell'API On-Premises a ricevere messaggi.

Passaggio 4: configurazione delle partizioni

Una volta registrato il client, puoi configurare le partizioni se necessario.

Passaggio 5: inizio dell'invio di messaggi

Ora puoi iniziare a inviare messaggi ai tuoi clienti. Consulta le guide Invio di messaggi per indicazioni.